Как создать свой MCP сервер: пошаговая инструкция для разработчика

MCP (Model Context Protocol) — открытый протокол, который позволяет ИИ-моделям обращаться к внешним инструментам, данным и API через единый интерфейс. Разобраться, как создать свой MCP сервер, проще всего на официальном SDK — для Python или TypeScript. Ниже — рабочие команды и минимальный код для старта.

Что понадобится перед стартом

ВариантТребованияПакетный менеджер
PythonPython 3.10+`uv` (рекомендуется) или `pip`
TypeScript/Node.jsNode.js, npm`npm`

Для Python-варианта официальная документация рекомендует менеджер uv — он быстрее ставит зависимости и удобно управляет виртуальным окружением.

Шаг 1. Создать MCP сервер на Python

Установите зависимости и инициализируйте проект:

bash
uv init mcp-server-demo
cd mcp-server-demo
uv add "mcp[cli]"

Если работаете через pip, extra-пакет ставится так:

bash
pip install "mcp[cli]"

Создайте файл server.py:

python
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Demo")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Складывает два числа"""
    return a + b

if __name__ == "__main__":
    mcp.run()

FastMCP — обёртка, которая берёт на себя регистрацию инструментов, обработку транспорта и сериализацию. Декоратор @mcp.tool() превращает обычную функцию в инструмент, доступный клиенту.

Шаг 2. Запустить и протестировать сервер

Для локальной отладки с инспектором MCP используйте:

bash
uv run mcp dev server.py

Команда поднимает сервер и открывает инструмент для проверки вызовов инструментов без подключения к реальному ИИ-клиенту.

Чтобы просто запустить сервер как процесс:

bash
uv run server.py

Шаг 3. Альтернатива — MCP сервер на TypeScript

Если ваш стек — Node.js, ставьте официальный TypeScript SDK вместе с обязательной peer-зависимостью zod (используется для валидации схем инструментов):

bash
npm install @modelcontextprotocol/sdk zod

Базовая структура сервера строится вокруг класса McpServer из SDK: вы создаёте экземпляр сервера, регистрируете инструменты с описанием входных параметров через схемы zod, а затем подключаете транспорт (stdio или SSE) для связи с клиентом.

Шаг 4. Подключить сервер к клиенту (Claude Desktop, Cursor)

После того как сервер запускается локально без ошибок, его нужно зарегистрировать в конфигурации клиента — обычно это JSON-файл с описанием команды запуска (путь к интерпретатору, путь к скрипту сервера, переменные окружения). Для Cursor и аналогичных IDE-клиентов сервер добавляется как MCP-провайдер во внутренние настройки проекта — так клиент узнаёт, какие инструменты доступны, и начинает вызывать их в диалоге.

Типичные ошибки при создании MCP сервера

  • Забыли extra `[cli]` при установке mcp — команды mcp dev и mcp run недоступны, импорт падает с ошибкой отсутствующего модуля.
  • Версия Python ниже 3.10 — SDK не устанавливается или падает при импорте типов.
  • Не поставили `zod` для TypeScript SDK — ошибки валидации схем инструментов при регистрации.
  • Функция не обёрнута декоратором/методом регистрации — инструмент не появляется в списке для клиента, хотя код выполняется без ошибок.
  • Неверный путь или интерпретатор в конфиге клиента — сервер не запускается из Claude Desktop/Cursor, хотя локально работает через uv run или node.

FAQ

Что такое MCP сервер простыми словами?

Это программа, которая предоставляет ИИ-модели доступ к внешним функциям (инструментам), данным (ресурсам) и шаблонам запросов (промптам) через стандартный протокол MCP.

На каком языке лучше писать MCP сервер?

Официальные SDK есть для Python и TypeScript, это самый быстрый путь для старта. Также существуют реализации на Java (Spring Boot) и Go для более сложных корпоративных сценариев с OAuth и observability.

Как проверить, что сервер работает, до подключения к клиенту?

Используйте встроенный режим отладки — команда uv run mcp dev server.py запускает сервер вместе с инспектором для ручной проверки вызовов инструментов.

Нужен ли отдельный хостинг для MCP сервера?

Нет, для локальной разработки и подключения к Claude Desktop или Cursor сервер обычно запускается как локальный процесс через stdio-транспорт. Хостинг нужен, только если сервер должен быть доступен внешним клиентам через сеть (SSE/HTTP).

Можно ли создать MCP сервер без написания кода на Python или TypeScript?

Официальные SDK охватывают Python и TypeScript как основные варианты; для других языков (Java, Go) существуют отдельные фреймворки и примеры реализации, но базовый путь для быстрого старта — именно эти два SDK.

Источники

  • https://modelcontextprotocol.io/docs/2024-11-05/develop/build-server
  • https://py.sdk.modelcontextprotocol.io/
  • https://ts.sdk.modelcontextprotocol.io/
  • https://developers.openai.com/plugins/build/mcp-server
  • https://modelcontextprotocol.org/docs/2025-03-26/develop/build-server
  • https://ru.hexlet.io/qna/mcp/questions/kak-sozdat-svoy-mcp-server
  • https://docs.oracle.com/en/database/oracle/agent-factory/25.3/paias/build-your-own-mcp-server.html
  • https://pkg.go.dev/github.com/go-training/mcp-workshop@v0.1.0