Как с помощью Claude создать MCP-сервер: рабочий гайд без воды (2026)
Короткий ответ. Открываете Claude Code, просите сгенерировать сервер на официальном Python SDK, запускаете через MCP Inspector и подключаете одной командой claude mcp add. Полчаса, если руки помнят терминал. Ниже — подробно, по шагам, с одной ловушкой, на которую сейчас натыкаются почти все, кто пишет по старым туториалам.
Что такое MCP и почему это перестало быть экзотикой
MCP (Model Context Protocol) — открытый стандарт от Anthropic, представленный в ноябре 2024 года. Идея простая, как USB-C: любой совместимый клиент (Claude, Cursor, VS Code) подключается к любому совместимому серверу без кастомного клея под каждую интеграцию. Раньше под каждый инструмент писали отдельную обвязку, теперь сервер один раз объявляет свои возможности — и его видят все.
Экзотикой это быть перестало по цифрам. К середине 2026 года через официальные Tier-1 SDK идёт под полмиллиарда загрузок в месяц, а серверов в экосистеме уже тысячи. 28 июля 2026 вышла спецификация 2026-07-28: ядро протокола стало stateless, то есть удалённый сервер спокойно живёт за обычным балансировщиком без липких сессий. Для локального сервера это ничего не ломает, но знать полезно.
Сервер оперирует тремя сущностями. Tools — функции, которые ИИ вызывает, чтобы что-то сделать (выполнить SQL, дёрнуть API, отправить сообщение). Resources — данные, которые можно прочитать, но не изменить (схема БД, лог, файл). Prompts — заготовки промптов. Дальше вся статья крутится вокруг Tools, потому что с них начинают в 99% случаев.
Что понадобится
- Python 3.10 или новее.
uv— менеджер проектов и зависимостей (быстрее pip, официально рекомендован в SDK).- Claude Code или Claude Desktop — смотря куда будете подключать готовый сервер.
- 30 минут и терминал.
Шаг 1. Поднимаем окружение
Создаём проект и ставим SDK с CLI-расширением. Флаг [cli] добавляет команды mcp dev, mcp run и mcp install — без них тестировать будет неудобно.
uv init my-mcp-server
cd my-mcp-server
uv add "mcp[cli]"Одна логическая единица сделана: у вас есть изолированное окружение, куда встанет всё остальное.
Шаг 2. Пусть черновик напишет Claude
Здесь и вступает в игру Claude. Открываете Claude Code в папке проекта и даёте конкретное ТЗ, а не расплывчатое «сделай мне сервер». Например:
«Создай MCP-сервер на официальном Python SDK версии 2. Добавь инструмент, который принимает город и возвращает заглушку с погодой. Транспорт stdio. Используй тип-хинты и docstring для каждого инструмента.»
Claude Code сам создаст server.py, впишет зависимости, запустит и, если что-то отвалится, прочитает traceback и починит. Смысл не в том, чтобы он думал за вас, а в том, чтобы вы не набивали boilerplate руками и сразу видели рабочий каркас. Дальше вы правите под свою задачу.
Шаг 3. Код сервера и ловушка с именем
Вот тот самый капкан. Летом 2026 официальный Python SDK вышел в версии 2.0.0 и переименовал класс FastMCP в MCPServer, заодно переехав из модуля mcp.server.fastmcp. Половина туториалов в сети всё ещё показывает старый импорт, код по ним на свежем SDK падает с ModuleNotFoundError. Актуальный минимальный сервер выглядит так:
# server.py
from mcp.server import MCPServer
mcp = MCPServer("Demo")
@mcp.tool()
def add(a: int, b: int) -> int:
"""Сложить два числа."""
return a + b
@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
"""Поприветствовать по имени."""
return f"Привет, {name}!"Обратите внимание, чего вы не написали: ни строчки JSON Schema, ни парсинга запроса, ни валидации. Тип-хинты a: int, b: int и есть схема, docstring становится описанием инструмента. Всё остальное SDK берёт на себя.
Три уточнения, чтобы не запутаться в версиях:
- Сидите на SDK 1.x — тогда рабочий импорт прежний:
from mcp.server.fastmcp import FastMCP. Чтобы случайно не подтянуть двойку, ставьте"mcp[cli]<2". - Есть отдельный пакет
fastmcp(проект Prefect, ставитсяpip install fastmcp, дока на gofastmcp.com). Это не то же самое, что модуль внутри официального SDK. FastMCP 1.0 когда-то влили в SDK, а FastMCP 2.0 живёт своей жизнью и добавляет auth, деплой, проксирование. Для первого сервера он не обязателен, но если позже упрётесь в прод-задачи вроде корпоративной авторизации, посмотрите в его сторону. - Просите Claude явно указывать целевую версию SDK в промпте. Иначе он может смешать старый и новый синтаксис.
Шаг 4. Запуск и проверка
Быстрее всего проверить сервер через MCP Inspector — он идёт в комплекте с CLI:
uv run mcp dev server.pyОткроется веб-интерфейс, где видно список инструментов, и каждый можно дёрнуть руками, не подключая пока никакого клиента. Если поднимаете сервер по HTTP, Inspector коннектится на http://localhost:8000/mcp.
Про транспорты коротко. Локально по умолчанию работает stdio: клиент запускает ваш скрипт и общается через стандартный ввод-вывод, данные никуда наружу не уходят. Для удалённого сервера используется Streamable HTTP:
uv run mcp run server.py --transport streamable-httpСтарый транспорт SSE считается устаревшим, новые серверы на него закладывать не стоит.
Шаг 5. Подключаем к Claude
Claude Code. Одна команда, и сервер в строю:
claude mcp add my-server -- uv run mcp run /полный/путь/server.pyДля удалённого HTTP-сервера синтаксис такой (пример на публичном сервере GitHub):
claude mcp add --transport http github https://api.githubcopilot.com/mcp/Дальше внутри Claude Code команда /mcp покажет статус и, если нужно, проведёт через авторизацию. Конфиг Claude Code лежит в ~/.claude.json.
Claude Desktop. Здесь через JSON-файл claude_desktop_config.json:
{
"mcpServers": {
"my-server": {
"command": "uv",
"args": ["run", "mcp", "run", "/полный/путь/server.py"]
}
}
}После правки конфиг надо не просто закрыть окно, а полностью выйти из приложения и открыть заново. Если сервер уже настроен в Desktop, в Claude Code его можно импортировать командой claude mcp add-from-claude-desktop.
Частые ошибки, на которых теряют время
- Пишут по старым гайдам. Импорт
FastMCPна SDK 2.x не заведётся. Либо новыйMCPServer, либо пин версии<2. - Не перезапустили Claude Desktop до конца. Закрытая вкладка — не перезапуск. Нужен полный выход и повторный старт.
- Битый JSON в конфиге. Лишняя запятая — и сервер молча не появляется. Прогоните файл через любой валидатор.
- Путают два конфига. Claude Code и Claude Desktop держат MCP-серверы в разных местах. Сервер, добавленный в Desktop, сам по себе не появится в Code, даже если Code запущен внутри Desktop.
- Закладываются на SSE. Транспорт устаревший, для нового сервера берите Streamable HTTP.
Вывод
Собрать MCP-сервер в 2026 году — это не про протокол и не про JSON-RPC руками. Это два тип-хинтованных питоновских метода, docstring и одна команда подключения. Claude Code снимает рутину скелета и отладки, а вы держите в голове ровно один нюанс: следите за версией SDK, чтобы не притащить старый FastMCP туда, где уже живёт MCPServer. Остальное протокол делает сам.
Отправить комментарий