Свой MCP-сервер с нуля — Python туториал

Вы когда-нибудь хотели, чтобы ваш ИИ-ассистент мог напрямую работать с вашей CRM, базой данных или файловой системой? MCP-сервер (Model Context Protocol) — это стандарт, который позволяет это сделать. По данным ToolBench от Arcade, в 2026 году уже проиндексировано 41 921 MCP-сервер и 218 422 инструмента — но 76,6% из них получили оценку F (меньше 50 баллов из 100). В этой статье мы разберём, как написать качественный MCP-сервер на Python с нуля, избежав типичных ошибок.

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

MCP (Model Context Protocol) — это открытый протокол, который позволяет ИИ-моделям (например, ChatGPT, Claude) вызывать внешние инструменты и получать доступ к данным. MCP-сервер — это программа, которая реализует этот протокол и предоставляет набор tools, resources и prompts. В отличие от обычного API, MCP требует строгого соблюдения handshake, описания capabilities и корректных ответов в формате JSON-RPC.

Зачем вам свой сервер? Готовые решения часто не дают гибкости, а многие публичные серверы работают нестабильно. Исследование 30 публичных MCP-серверов показало, что 14 из 30 (46,7%) не смогли даже запуститься — ошибка на этапе launch/init. Свой сервер вы контролируете полностью.

⚡ Факт: Только 0,5% инструментов в ToolBench получили оценку A или выше — это значит, что даже опубликованные серверы часто содержат ошибки.

Архитектура MCP-сервера на Python

MCP-сервер состоит из трёх основных компонентов:

• Transport layer — отвечает за связь с клиентом (stdin/stdout, HTTP, WebSocket).
• Protocol handler — обрабатывает JSON-RPC сообщения, выполняет handshake.
• Tool/Resource definitions — ваши функции, которые вызываются по запросу.

Для Python есть официальный SDK: github.com/modelcontextprotocol. В нём уже реализованы базовые классы для сервера, так что вам остаётся только описать инструменты.

Установка и настройка окружения

Создайте виртуальное окружение и установите пакет:

pip install mcp

После установки можно создать файл server.py и импортировать mcp.server. Убедитесь, что версия Python >= 3.10.

Пошаговое создание MCP-сервера

Рассмотрим минимальный пример — сервер, который умеет складывать два числа и возвращать текущее время.

Шаг 1: Базовый каркас

Создайте экземпляр сервера и определите его имя:

from mcp.server import Server

server = Server("my-calculator")

Шаг 2: Определите инструменты

Каждый инструмент — это функция с декоратором @server.tool. Обязательно опишите схему с помощью type hints или pydantic:

from mcp.server import tool

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

@tool(description="Возвращает текущее время в формате HH:MM:SS")
def current_time() -> str:
    from datetime import datetime
    return datetime.now().strftime("%H:%M:%S")

Шаг 3: Запустите сервер

Используйте транспорт stdin/stdout (по умолчанию):

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

Запустите скрипт: python server.py. Сервер будет ждать сообщений от клиента. Для теста можно использовать MCP Inspector или написать простой клиент.

⚡ Факт: В исследовании 30 публичных серверов у 4 из 11 (36%) серверов, требующих env-переменные, запуск прошёл успешно без секретов. Убедитесь, что ваш сервер не падает при отсутствии переменных.

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

Чтобы ваш сервер не пополнил статистику 76,6% неудачных, избегайте следующих ошибок:

1. Игнорирование описаний инструментов. Клиент использует описание для выбора инструмента. Если описание пустое или неинформативное — инструмент не вызовут.
2. Некорректная обработка ошибок. Любое исключение внутри инструмента должно возвращать JSON-RPC ошибку, а не крашить сервер.
3. Отсутствие таймаутов. Долгие операции (запросы к БД, файловые операции) должны иметь таймаут, иначе клиент зависнет.
4. Хардкод секретов. Никогда не пишите токены, пароли или ключи прямо в коде — используйте переменные окружения.
5. Плохая валидация входных данных. Всегда проверяйте типы и диапазоны. Злоумышленник может передать строку вместо числа и сломать сервер.

Продвинутый пример: сервер для работы с файлами

Рассмотрим более сложный сервер, который читает и записывает файлы в заданной директории. Это полезно для локального ИИ-ассистента.

import os
from mcp.server import Server, tool

server = Server("file-manager")
ALLOWED_DIR = os.environ.get("ALLOWED_DIR", ".")

@tool(description="Читает содержимое файла. Путь должен быть внутри ALLOWED_DIR.")
def read_file(path: str) -> str:
    full_path = os.path.abspath(os.path.join(ALLOWED_DIR, path))
    if not full_path.startswith(os.path.abspath(ALLOWED_DIR)):
        raise PermissionError("Доступ запрещён")
    with open(full_path, "r") as f:
        return f.read()

@tool(description="Записывает текст в файл. Создаёт файл, если он не существует.")
def write_file(path: str, content: str) -> bool:
    full_path = os.path.abspath(os.path.join(ALLOWED_DIR, path))
    if not full_path.startswith(os.path.abspath(ALLOWED_DIR)):
        raise PermissionError("Доступ запрещён")
    with open(full_path, "w") as f:
        f.write(content)
    return True

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

Обратите внимание: мы проверяем, что файл находится внутри разрешённой директории, чтобы избежать path traversal. Безопасность — ответственность сервера, а не только клиента.

⚡ Факт: По данным Arcade ToolBench, только 0,5% инструментов получили оценку A или выше. Качественная валидация и безопасность — то, что отличает хороший сервер от среднего.

Тестирование и отладка MCP-сервера

Для тестирования используйте MCP Inspector — графический инструмент, который подключается к вашему серверу и позволяет вызывать инструменты вручную. Также можно написать простой клиент на Python:

from mcp.client import Client

client = Client("stdio", command=["python", "server.py"])
result = client.call_tool("add", {"a": 2, "b": 3})
print(result)  # 5

Проверьте, что сервер корректно обрабатывает ошибки — например, при неверных аргументах возвращает ошибку, а не падает.

Заключение: MCP-сервер для регионального бизнеса

Для компаний в Саратовской области и других регионах MCP-сервер — это возможность интегрировать ИИ в существующие процессы без дорогих платформ. Вы можете написать сервер на Python, развернуть его на обычном VPS или локальном Linux-хосте и подключить к CRM, учётным системам или документам. Стоимость внедрения — только время разработчика, а результат — автоматизация рутины.

Наш опыт показывает, что средний MCP-сервер для внутренних нужд можно написать за 2-3 дня. При этом вы полностью контролируете безопасность и функциональность.

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