Как создать MCP-сервер на Python: рабочий пример

Чтобы создать MCP-сервер на Python, установи SDK, опиши функцию как инструмент и запусти сервер с транспортом stdio. MCP-клиент сможет узнать имя функции, увидеть схему аргументов и вызвать её. В этом примере сервер возвращает сведения об уроке из маленького каталога.

Получится локальный сервер с одним инструментом get_lesson. Он работает без ключа к модели: Python-функция сама находит запись и формирует ответ. Модель понадобится на стороне клиента, когда ты попросишь Cursor выбрать и вызвать инструмент естественным языком.

Что собираем

Возьмём вымышленную программу из трёх уроков: intro, tools, checks. Это учебные данные, а не описание реальных курсов. В ответе сервер отдаёт название и длительность. Если ID не существует, он сообщает об этом и перечисляет допустимые значения.

Путь запроса: твой вопрос → Agent в Cursor → get_lesson → словарь в Python → ответ инструмента → объяснение модели. Сервер не читает диск, не обращается к сети и не изменяет данные. Такая маленькая задача помогает проверить механику до подключения базы или внешнего API.

Пример использует официальный пакет mcp==2.2.0. В SDK 2.x для этого есть MCPServer; в старых руководствах встречается другой импорт с FastMCP. Сверяй пример с установленной версией. Требования и начальный пример есть в документации Python SDK.

1. Подготовь окружение

Скачай проект и распакуй в отдельную папку. Нужен Python 3.10 или новее. В терминале из этой папки создай виртуальное окружение:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -c "import importlib.metadata; print(importlib.metadata.version('mcp'))"

На Windows используй py -m venv .venv, а следующие команды запускай через .venv\Scripts\python.exe. В последней строке ожидается 2.2.0. Виртуальное окружение удерживает зависимости примера отдельно от других Python-проектов.

Если команда python3 не найдена, сначала установи Python и проверь его доступность в терминале. Если установленная сборка не содержит pip или venv, исправь установку Python. Не пытайся компенсировать это случайным запуском системного pip: пакет может попасть к другому интерпретатору.

2. Создай инструмент

В архиве уже есть server.py:

from mcp.server import MCPServer

mcp = MCPServer("demo-lessons")
LESSONS = {
    "intro": {"title": "Первый агент", "minutes": 25},
    "tools": {"title": "Подключение инструментов", "minutes": 40},
    "checks": {"title": "Проверка результата", "minutes": 30},
}

@mcp.tool()
def get_lesson(lesson_id: str) -> dict:
    """Вернуть урок учебного каталога по ID: intro, tools или checks."""
    key = lesson_id.strip().lower()
    lesson = LESSONS.get(key)
    if lesson is None:
        return {"found": False, "lesson_id": key, "available_ids": list(LESSONS)}
    return {"found": True, "lesson_id": key, **lesson}

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

Здесь название функции становится именем инструмента. Аннотация lesson_id: str описывает аргумент, а строка документации объясняет назначение. При успешном поиске ответ содержит found: true. Неизвестный урок — ожидаемый результат поиска, поэтому возвращаем found: false, а не придумываем данные.

Запусти .venv/bin/python server.py. Процесс может молчать: он ждёт сообщения протокола в стандартном вводе. Не вводи туда обычный вопрос. Останови ручной запуск через Ctrl+C, затем дай клиенту запустить свою копию процесса.

Не добавляй обычный print() для приветствия: стандартный вывод занят протоколом. Для отладочного сообщения используй print("сообщение", file=sys.stderr) после import sys.

3. Подключи к Cursor

В открытом проекте Cursor добавь в .cursor/mcp.json такую запись, заменив оба пути на абсолютные пути своего компьютера:

{
  "mcpServers": {
    "demo-lessons": {
      "type": "stdio",
      "command": "/absolute/path/mcp-server-python/.venv/bin/python",
      "args": ["/absolute/path/mcp-server-python/server.py"]
    }
  }
}

На Windows в command укажи путь к .venv/Scripts/python.exe. Прямые слеши в JSON избавляют от необходимости экранировать обратные. Не сохраняй пример с /absolute/path/ буквально. Если конфигурация уже содержит другие серверы, добавь объект внутрь существующего mcpServers.

В настройках MCP проверь, что demo-lessons запущен и предоставляет get_lesson. Формат соединения сверяется с документацией Cursor. Более подробный разбор интерфейса есть в статье о подключении MCP к Cursor.

4. Проверь ответы

Отправь Agent задание:

Через MCP demo-lessons вызови get_lesson с lesson_id="intro".
Покажи ID, название и длительность из ответа инструмента.
Затем вызови его с lesson_id="missing". Не подбирай замену самостоятельно.

В карточках вызовов проверь именно аргументы и возвращённые данные. Красивое объяснение без вызова не подтверждает подключение.

Вход	Ожидаемый ответ
`intro`	`found=true`, 25 минут
`tools`	`found=true`, 40 минут
`checks`	`found=true`, 30 минут
`INTRO`	Нормализованный ID `intro`, 25 минут
`missing` или пустая строка	`found=false`, список допустимых ID
Аргумент `lesson_id` отсутствует	Ошибка валидации вызова

При подготовке материала сервер проверен через MCP: инициализация, получение списка инструментов, успешные ответы, неизвестный ID и пропущенный аргумент. Вызов из интерфейса Cursor отдельно не проверялся. Эти два уровня проверки различаются: исправный сервер ещё нужно корректно подключить к своему клиенту.

Ошибки и следующий шаг

ModuleNotFoundError: mcp обычно означает, что клиент запускает Python без установленного пакета. Сверь command с интерпретатором виртуального окружения. Ошибка импорта MCPServer требует проверки версии SDK. Сообщение о невозможности открыть файл — проверки пути в args.

Если инструмент появился, но возвращает старые данные, перезапусти MCP-подключение после изменения кода. Если инструмент не вызывается, уточни имя сервера и ID в запросе, затем проверь доступность инструмента в текущем чате.

Следующее полезное расширение — заменить словарь чтением своего справочника и добавить тест на отсутствующую запись. Доступ к базе, проверку прав и ограничения запросов придётся реализовать отдельно: MCP задаёт способ взаимодействия, но не делает произвольную Python-функцию безопасной автоматически.

Todo: попробуй на своей задачеУстановить SDK в отдельное окружениеЗапустить сервер через stdioПолучить урок через get_lessonПроверить неизвестный IDПрогресс сохраняется в этом браузере.

ПРАКТИКА НА КУРСЕ / AI PRODUCT CLUB

Собери своего ИИ-агента и проверь результат

«AI Agents: от vibe coding к AI-команде»: desktop agents, MCP, skills, evals и harness. Отдельные воркшопы — от подключения инструментов до контроля качества.

7 практических воркшопов · записи · вопросы автору в чате

Посмотреть программу курса ↗

Автор: Михаил Карпов — практик автоматизации и автор курсов AI Product Club.