Как создать MCP-сервер на Python: гайд

Коротко

MCP-сервер — это небольшая программа, которая по единому протоколу отдаёт ИИ-ассистенту (Claude Code, Cursor, Claude Desktop) готовые инструменты, данные и подсказки. На Python минимальный рабочий сервер — это 10–15 строк: объект FastMCP, функции с декоратором @mcp.tool() и вызов mcp.run(). Дальше сервер подключается к клиенту одной командой, отлаживается в MCP Inspector и требует аккуратной работы с безопасностью. Если своя интеграция не нужна — быстрее взять готовое решение из подборки MCP-серверов или раздела «Арсенал».

Что такое MCP-сервер и зачем он нужен

MCP (Model Context Protocol) — это открытый протокол, который стандартизирует, как языковая модель обращается к внешним инструментам и данным. Вместо самописных интеграций под каждый клиент вы описываете возможности один раз — и любой MCP-совместимый ассистент их видит.

MCP-сервер — это процесс, который реализует серверную сторону протокола: объявляет свои возможности и выполняет запросы клиента (host). Общение идёт по JSON-RPC 2.0, поэтому язык реализации не важен — важен контракт.

Сервер отдаёт три типа возможностей (примитивов):

Примитив	Что это	Пример
Инструмент (tool)	Функция, которую модель вызывает с аргументами	`get_forecast(city)`
Ресурс (resource)	Данные, которые модель читает по URI	`config://app`
Промпт (prompt)	Шаблон-подсказка, который подставляется в диалог	«сделай ревью diff»

Писать свой сервер стоит, когда нужен доступ к внутреннему API, приватной базе или нестандартной логике. Для типовых задач (GitHub, файлы, браузер, БД) серверы уже написаны — начните с их обзора, чтобы не изобретать велосипед.

Что понадобится: SDK и окружение

Минимальный набор на июль 2026:

Python 3.10+.
Официальный SDK mcp (на июль 2026 — версия 1.28.x, лицензия MIT). Ставится: pip install "mcp[cli]" или uv add "mcp[cli]". Extras [cli] дают Inspector для отладки.
Внутри официального пакета уже лежит FastMCP — высокоуровневый слой, который прячет JSON-RPC за декораторами.
Альтернатива — отдельный пакет fastmcp (на июль 2026 — линейка 3.x). Он развивается быстрее официального и импортируется как from fastmcp import FastMCP.
Изолированное окружение: держите сервер в отдельном venv или под uv. Клиент запускает его своим интерпретатором, и лишние пакеты в системном Python — частый источник плавающих ошибок вида «работает только у меня».

Честная оговорка: у официального SDK есть бета-линейка нового поколения. Для продакшена в июле 2026 берите стабильную версию, а бету — только для экспериментов.

Как выглядит минимальный сервер на Python

Полноценный сервер с одним инструментом:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("weather")

@mcp.tool()
def get_forecast(city: str) -> str:
    """Вернуть краткий прогноз погоды для указанного города."""
    # здесь — реальный вызов внешнего API
    return f"{city}: +18°C, ясно"

if __name__ == "__main__":
    mcp.run()  # транспорт по умолчанию — stdio

Ключевая идея: тип-хинты и докстринг — это не украшение, а схема инструмента, которую видит модель. Имя функции, типы аргументов и текст описания — ровно то, по чему ассистент решает, вызывать инструмент и с какими параметрами. Расплывчатый докстринг = неверные вызовы. Описывайте инструменты так же тщательно, как ставите задачу субагенту.

Инструмент может быть и асинхронным — объявите его через async def, и внутри спокойно дожидайтесь сетевых вызовов, не блокируя сервер. Возвращаемое значение сериализуется автоматически: строку, число, словарь или Pydantic-модель модель получит как структурированный результат, а не как безликий текст, — поэтому продуманный тип ответа так же важен, как имя и описание.

Ресурс объявляется так же просто — декоратором @mcp.resource("config://app") над функцией, которая возвращает данные по этому URI.

Как запустить и подключить сервер к Claude Code и Cursor

Запуск локально в режиме stdio:

python server.py

stdio — это транспорт, при котором клиент сам запускает сервер как подпроцесс и обменивается сообщениями через стандартные потоки ввода-вывода. Для локальных ассистентов это дефолт. Всего транспортов три:

Транспорт	Что это	Когда брать
stdio	Клиент запускает сервер как подпроцесс	Локальные интеграции, дефолт
Streamable HTTP	Сервер живёт на HTTP-эндпоинте	Прод, удалённый доступ, много клиентов
SSE	Server-Sent Events поверх HTTP	Легаси; для нового кода лучше Streamable HTTP

Подключить к Claude Code — одна команда CLI:

claude mcp add weather -- python /абсолютный/путь/server.py

Всё после -- передаётся серверу как команда запуска; флаги --transport, --env, --scope ставятся до имени. В Cursor и Claude Desktop сервер прописывается в конфиге JSON вручную. Пошагово оба сценария разобраны в отдельном гайде — как подключить MCP к Claude Code.

После добавления убедитесь, что клиент действительно увидел сервер: в Claude Code команда /mcp показывает подключённые серверы и их статус, в Cursor — переключатель в настройках MCP. Статус «failed» почти всегда означает ошибку пути или окружения — проверяйте их в первую очередь, а уже потом сам код.

Как отладить MCP-сервер

Главный инструмент — MCP Inspector, веб-интерфейс, где видны объявленные инструменты и их можно вызвать руками:

mcp dev server.py

Три частые ошибки:

print() в stdout ломает stdio. В режиме stdio стандартный вывод занят кадрами JSON-RPC. Любой print() в stdout повреждает поток — логируйте только в stderr или в файл.
Сервер не появился у клиента. Почти всегда это относительный путь или не тот интерпретатор. Указывайте абсолютный путь и то же виртуальное окружение, где установлен SDK.
Инструмент есть, но не вызывается. Модель не понимает, зачем он. Уточните докстринг и имена аргументов — это и есть «интерфейс» для модели.

Безопасность: что нельзя упускать

MCP-сервер — это код, который выполняет действия по «просьбе» модели, а на входе у него недоверенный текст. Базовый чек-лист:

Не доверяйте аргументам. Валидируйте всё, что приходит от модели, как пользовательский ввод: пути, SQL, shell-команды.
Принцип наименьших привилегий. Дайте серверу ровно тот доступ, который нужен инструменту, и не шире.
Секреты — в переменных окружения, не в коде и не в докстрингах (докстринг уходит модели).
Prompt injection через ответ. Если инструмент возвращает внешний текст (веб-страницу, письмо), модель может воспринять его как инструкцию. Помечайте такие данные как данные, а не как команды.
Подтверждение для необратимого. Удаление, платежи, отправка сообщений — только с явным подтверждением человека.

От своего сервера — к готовому контуру

Свой MCP-сервер — правильный выбор для уникальной интеграции. Но большинство повседневных задач закрывают уже написанные серверы плюс отлаженный рабочий процесс. В разделе «Арсенал» собраны проверенные серверы с настройкой, а движок вайб-кодинга Quest (на июль 2026 — 4900 ₽ за движок разово, без подписки; модули по 1900 ₽) даёт готовый контур: правила, промпты и связку инструментов, чтобы Claude Code сразу работал предсказуемо. Если задача — расширить ассистента без написания сервера, посмотрите в сторону Claude Skills: часто это быстрее.

Частые вопросы

Чем MCP-сервер отличается от Skill или плагина?

MCP-сервер даёт модели новые инструменты и данные по протоколу и работает с любым MCP-клиентом. Skill — это набор инструкций и файлов, который расширяет поведение конкретно Claude без отдельного процесса. Часто их комбинируют: сервер даёт доступ, Skill — методику.

Обязательно ли писать сервер на Python?

Нет. В основе — JSON-RPC, а SDK есть для многих языков. Python выбирают за скорость прототипа и богатую экосистему, но контракт одинаков для всех реализаций.

Нужен ли отдельный сервер под каждый инструмент?

Нет. Один сервер может объявлять десятки инструментов и ресурсов. Группируйте по домену: один сервер — одна внешняя система или один связанный набор задач.

stdio или HTTP — что выбрать?

Для локального ассистента на своей машине — stdio: это дефолт и не требует сети. Если сервер общий, крутится на удалённой машине или обслуживает несколько клиентов — Streamable HTTP с TLS.

Как это работает из России?

Сам SDK и запуск сервера от региона не зависят — это открытый код. Ограничения касаются доступа к самому ассистенту и API Anthropic; легально это решается через агрегаторы и зарубежные карты. Детали — в гайде Claude API из России.