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

MCP сервер на Python пишется примерно за 50 строк кода. Официальный SDK от Anthropic настолько хорошо сделан, что рабочий инструмент для Claude Code или Cursor получается быстрее, чем настройка любого REST API.

В этом гайде разберем полный процесс: от установки UV и инициализации проекта до теста сервера в Claude Desktop. Плюс объясним, в чем реальная разница между инструментом (tool), ресурсом (resource) и промптом (prompt). Три понятия, которые путают чаще всего.

Статья для тех, кто уже пишет код на Python, хочет подключить свои инструменты к AI-агентам и не хочет тратить день на разбор документации.

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

MCP расшифровывается как Model Context Protocol. Anthropic выпустил стандарт в ноябре 2024 года, и за полтора года его поддержали Claude, ChatGPT, Cursor, Windsurf, VS Code Copilot и десятки других инструментов. В декабре 2025 года протокол был передан в Linux Foundation под управление Agentic AI Foundation. Стандарт стал официально независимым от одного вендора.

Смысл простой. До MCP каждый разработчик писал свою интеграцию: хочешь подключить AI к базе данных: пишешь коннектор. Хочешь к API: пишешь другой. При N инструментах и M источников данных получалось N×M кастомных подключений. MCP решает это одним стандартом: написал сервер один раз, он работает со всеми клиентами, которые поддерживают протокол.

Практически это выглядит так: в Claude Code или Cursor прописываешь конфигурацию своего сервера, и AI-агент видит твои инструменты наравне со встроенными. Попросил «добавь 100 фейковых пользователей в базу», агент вызывает твой инструмент и делает именно это, без лишних скриптов и копипасты.

Максим: «Когда я строил NanaBanana, одной из больных точек была ручная работа с данными. Сейчас MCP сервер это закрывает полностью: подключил к Claude Desktop и говорю агенту что нужно сделать. Экономия три-четыре часа в неделю, и это только на рутине.»

Три компонента MCP сервера: tool, resource, prompt

Прежде чем лезть в код, надо понять архитектуру. MCP сервер может предоставлять три типа объектов клиенту.

Tool (инструмент): действие, которое что-то делает. Создает запись, вызывает API, пишет в файл, генерирует данные. Аналог POST-эндпоинта. AI-агент вызывает tool тогда, когда нужно что-то сделать, а не просто получить информацию.

Resource (ресурс): данные, которые можно прочитать. Содержимое файла, результат SQL-запроса, список чего-либо. Аналог GET-эндпоинта. Ресурс загружается в контекст модели как справочная информация.

Prompt (промпт): переиспользуемый шаблон инструкции. Если у тебя есть сложный промпт с параметрами, который ты хочешь вызывать многократно: оборачиваешь его в prompt-объект MCP.

Вот как они соотносятся по сценарию использования:

Тип	Что делает	Когда использовать
Tool	Действие с побочным эффектом	Запись в БД, вызов API, создание файла
Resource	Только читает данные	Загрузка контекста, справочники, история
Prompt	Шаблон инструкции	Повторяющиеся сценарии взаимодействия

Для большинства пользовательских серверов нужны только tools. Resources и prompts подключают по мере усложнения.

Установка: UV вместо pip

Официальная документация Python SDK от Anthropic рекомендует UV для управления проектом. И это не просто предпочтение: UV значительно быстрее pip при установке зависимостей и автоматически создает виртуальное окружение без дополнительных команд.

Установка на macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

На Windows через PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

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

uv init my-mcp-server
cd my-mcp-server

Устанавливаем SDK. Актуальная версия на май 2026: 1.27.1.

uv add "mcp[cli]"

Эта команда установит библиотеку MCP вместе с CLI-утилитой для регистрации сервера в Claude Desktop. Весь процесс занимает меньше минуты.

Минимальный рабочий MCP сервер: 50 строк кода

Открываем main.py и пишем сервер. Начнем с самого простого примера, который реально работает:

from mcp.server.fastmcp import FastMCP
import os

# Инициализируем сервер с именем
mcp = FastMCP("my-tools")

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

    Args:
        a: Первое число
        b: Второе число

    Returns:
        Сумма двух чисел
    """
    return a + b

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

Это и есть полный рабочий сервер. Декоратор @mcp.tool() регистрирует функцию как инструмент. Строки документации (docstring) критически важны: именно их читает AI-модель, чтобы понять когда и как вызывать инструмент.

Чем точнее описание в docstring, тем лучше агент выбирает нужный инструмент.

Как правильно писать docstrings для tools

Это один из самых частых вопросов. Плохой docstring приводит к тому, что агент либо не вызовет инструмент, либо вызовет в неподходящий момент.

Хорошо:

@mcp.tool()
def save_note(message: str, category: str = "general") -> str:
    """Сохраняет заметку в файл notes.txt.

    Используй этот инструмент когда пользователь просит сохранить,
    записать или запомнить какую-либо информацию.

    Args:
        message: Текст заметки для сохранения
        category: Категория заметки (general, task, idea)

    Returns:
        Подтверждение успешного сохранения
    """
    # реализация

Плохо:

@mcp.tool()
def save_note(message: str) -> str:
    """Сохраняет заметку."""
    # реализация

Правило простое: пиши docstring так, как объяснял бы коллеге: когда звонить по этому номеру и что ожидать в ответ.

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

Вот практический пример с тремя компонентами: tool, resource и prompt. Именно этот паттерн используют в большинстве реальных серверов:

from mcp.server.fastmcp import FastMCP
import os

mcp = FastMCP("sticky-notes")

# Путь к файлу заметок, относительно текущего скрипта
NOTES_FILE = os.path.join(os.path.dirname(__file__), "notes.txt")


def _ensure_file():
    """Создает файл заметок если не существует."""
    if not os.path.exists(NOTES_FILE):
        with open(NOTES_FILE, "w") as f:
            f.write("")


@mcp.tool()
def add_note(message: str) -> str:
    """Добавляет новую заметку в файл.

    Используй когда нужно сохранить, записать или запомнить информацию.

    Args:
        message: Текст заметки

    Returns:
        Подтверждение сохранения
    """
    _ensure_file()
    with open(NOTES_FILE, "a") as f:
        f.write(message + "\n")
    return "Заметка сохранена"


@mcp.tool()
def read_notes() -> str:
    """Читает все сохраненные заметки.

    Используй когда нужно показать список заметок или найти что-то ранее записанное.

    Returns:
        Содержимое файла заметок или сообщение об отсутствии заметок
    """
    _ensure_file()
    with open(NOTES_FILE, "r") as f:
        content = f.read().strip()
    return content if content else "Заметок пока нет"


@mcp.resource("notes://latest")
def get_latest_note() -> str:
    """Возвращает последнюю добавленную заметку."""
    _ensure_file()
    with open(NOTES_FILE, "r") as f:
        lines = f.readlines()
    return lines[-1].strip() if lines else "Заметок пока нет"


@mcp.prompt()
def summarize_notes() -> str:
    """Промпт для суммаризации всех заметок."""
    _ensure_file()
    with open(NOTES_FILE, "r") as f:
        content = f.read().strip()
    if not content:
        return "Заметок пока нет."
    return f"Суммаризируй эти заметки кратко:\n\n{content}"


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

Обрати внимание на _ensure_file(): вспомогательную функцию, которую стоит вызывать перед любой операцией с файлом. Без нее сервер падает при первом запуске, когда файла еще нет. На практике именно такие мелочи убивают время при отладке.

Транспорт: stdio и HTTP

MCP поддерживает два транспортных механизма: stdio (стандартный ввод-вывод) и HTTP.

stdio: дефолтный вариант для локальных серверов. Когда Claude Desktop или Cursor запускает твой сервер, он общается с ним через stdin/stdout. Быстро, просто, не требует открытых портов. Подходит для большинства случаев.

HTTP: нужен если хочешь запустить сервер как отдельный процесс или дать доступ нескольким клиентам одновременно. Настраивается так:

if __name__ == "__main__":
    mcp.run(transport="http", host="127.0.0.1", port=8000)

Для теста локально через stdio вызываешь просто mcp.run() без аргументов. Это и есть поведение по умолчанию.

Подключение к Claude Desktop

Самый быстрый способ протестировать сервер. CLI-команда:

uv run mcp install main.py

Она автоматически добавит конфигурацию в Claude Desktop. Если нужно сделать вручную, открой настройки Claude Desktop: Настройки → Developer → Edit Config и добавь:

{
  "mcpServers": {
    "my-tools": {
      "command": "uv",
      "args": ["run", "python", "main.py"],
      "cwd": "/абсолютный/путь/до/проекта"
    }
  }
}

Важный нюанс: путь в cwd должен быть абсолютным. Относительные пути работают непредсказуемо в зависимости от того, откуда стартует Claude Desktop.

После изменения конфига: полностью закрой Claude Desktop через диспетчер задач и открой заново. Просто закрыть окно недостаточно, процесс висит в фоне. Это лидер по числу потраченных часов при первом знакомстве с MCP.

Подключение к Cursor и Windsurf

Для Cursor конфиг живет в .cursor/mcp.json в корне проекта:

{
  "mcpServers": {
    "my-tools": {
      "command": "uv",
      "args": ["run", "python", "main.py"]
    }
  }
}

Для Windsurf: аналогичный формат в настройках MCP. После сохранения конфига кликаешь «Refresh MCP servers» и видишь свой сервер со статусом зеленого кружка.

Если статус красный, проверь в первую очередь путь к python и к проекту. Вторая частая причина: uv не найден в PATH, тогда нужно указать абсолютный путь до исполняемого файла.

Тестирование без IDE: MCP Inspector

MCP Inspector: браузерный интерфейс для проверки сервера без подключения к Claude или Cursor. Запускается одной командой:

npx @modelcontextprotocol/inspector

Открой http://localhost:5173, укажи URL своего сервера, и сразу увидишь список всех tools, resources и prompts. Можно вызывать их напрямую и смотреть ответы. Незаменимо при разработке.

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

Проблема 1: сервер не появляется в Claude Desktop после регистрации. Решение: полная перезагрузка: закрываешь через Task Manager, открываешь заново. Это нужно делать каждый раз после изменения конфига.

Проблема 2: файл создается не там, где ожидаешь. Если пишешь просто "notes.txt", файл появится в рабочей директории запущенного процесса, а не рядом со скриптом. Используй os.path.join(os.path.dirname(__file__), "notes.txt").

Проблема 3: агент не вызывает инструмент. Первое что проверяешь: docstring. Если описание расплывчатое или отсутствует, агент просто не понимает когда этот tool нужен.

Проблема 4: ошибка при импорте mcp. Проверь что используешь uv run python main.py, а не просто python main.py. При прямом запуске виртуальное окружение UV не активируется.

Кому подходит этот подход, а кому нет

MCP сервер на Python идеально подходит если:

У тебя есть Python-скрипты или инструменты, которые хочешь сделать доступными AI-агентам
Работаешь с Claude Code, Cursor или Windsurf и хочешь расширить их возможности
Строишь внутренний инструмент для команды

Не подходит если:

Нужна Production-ready инфраструктура с аутентификацией для внешних пользователей. Здесь стоит смотреть в сторону FastMCP с HTTP и OAuth
Команда не использует MCP-совместимые клиенты. Тогда проще обычный REST API

Пример из реальной практики: сервер для работы с базой данных

Вот как выглядит более практичный tool, добавление тестовых пользователей в SQLite:

import sqlite3
from mcp.server.fastmcp import FastMCP
import random
import string

mcp = FastMCP("db-tools")

DB_PATH = "users.db"


def _get_conn():
    conn = sqlite3.connect(DB_PATH)
    conn.execute("""
        CREATE TABLE IF NOT EXISTS users (
            id INTEGER PRIMARY KEY,
            name TEXT,
            email TEXT
        )
    """)
    conn.commit()
    return conn


@mcp.tool()
def create_fake_users(count: int = 10) -> str:
    """Создает указанное количество тестовых пользователей в базе данных.

    Используй при необходимости заполнить базу тестовыми данными.

    Args:
        count: Количество пользователей для создания (по умолчанию 10)

    Returns:
        Сообщение о количестве созданных пользователей
    """
    conn = _get_conn()
    for _ in range(count):
        name = "User_" + "".join(random.choices(string.ascii_letters, k=6))
        email = name.lower() + "@test.com"
        conn.execute("INSERT INTO users (name, email) VALUES (?, ?)", (name, email))
    conn.commit()
    conn.close()
    return f"Создано {count} пользователей"


@mcp.tool()
def count_users() -> int:
    """Возвращает количество пользователей в базе данных."""
    conn = _get_conn()
    result = conn.execute("SELECT COUNT(*) FROM users").fetchone()[0]
    conn.close()
    return result

После подключения такого сервера можно просто написать агенту «создай 50 тестовых пользователей», и он сделает это через твой инструмент. Никаких отдельных скриптов, никакой копипасты.

Глоссарий

MCP (Model Context Protocol): открытый стандарт Anthropic для интеграции AI-агентов с внешними инструментами и данными. Передан в Linux Foundation в декабре 2025.

Tool: функция MCP сервера, которая выполняет действие с побочным эффектом (запись, API-вызов, создание данных).

Resource: объект MCP сервера, предоставляющий данные только для чтения. Загружается в контекст модели.

Prompt: переиспользуемый шаблон инструкции в MCP сервере. Хранит сложные промпты с параметрами.

FastMCP: высокоуровневая обертка официального Python SDK для быстрого создания MCP серверов. Часть пакета mcp[cli].

UV: современный пакетный менеджер Python, рекомендованный Anthropic для MCP-проектов. Работает значительно быстрее pip.

stdio: транспорт MCP через стандартный ввод-вывод. Дефолтный вариант для локальных серверов.

docstring: строка документации Python-функции, которую MCP сервер использует для описания инструмента агенту.

MCP Inspector: браузерный интерфейс для тестирования MCP серверов без подключения IDE.

FAQ

Нужно ли знать асинхронный Python для написания MCP сервера?
Нет. FastMCP поддерживает обычные синхронные функции. Async поддерживается, но не обязателен для большинства задач.

Можно ли использовать один MCP сервер с несколькими IDE одновременно?
Да, если запустить сервер в режиме HTTP на фиксированном порту. При stdio каждый клиент запускает отдельный процесс сервера.

Где хранятся конфиги для Cursor и Claude Desktop?
Claude Desktop: системная папка конфигурации (открывается через Developer → Edit Config). Cursor: файл .cursor/mcp.json в корне проекта.

Как отлаживать MCP сервер?
Запусти MCP Inspector командой npx @modelcontextprotocol/inspector. В браузере увидишь все зарегистрированные tools и сможешь вызывать их вручную.

Какая минимальная версия Python нужна для MCP SDK?
Python 3.10 или выше. Это требование официального SDK от Anthropic.

Можно ли подключить сторонние библиотеки внутри MCP сервера?
Да. Это обычный Python-проект, можно использовать requests, SQLAlchemy, pandas и всё остальное. Добавляешь через uv add название_пакета.

Как MCP сервер защитить от несанкционированного доступа?
Для локальных серверов через stdio: защита не нужна, доступ только с локальной машины. Для HTTP-серверов с внешним доступом: используй токены авторизации и HTTPS. Официальная документация FastMCP описывает OAuth-интеграцию для продакшн-сценариев.

Итог

Создание MCP сервера на Python: это реально быстро. Официальный SDK от Anthropic (версия 1.27.1 на май 2026) + пакетный менеджер UV + FastMCP дают рабочий сервер за один вечер.

Ключевые шаги: установить UV, добавить пакет mcp[cli], написать функции с декоратором @mcp.tool() и хорошими docstrings, зарегистрировать через mcp install или вручную в конфиге Claude Desktop или Cursor.

Посмотри другие инструменты в каталоге AI-инструментов: там собраны все актуальные IDE и агенты с поддержкой MCP. Если хочешь разобраться с MCP серверами для своего конкретного проекта, запишись на консультацию к Максиму.

Обновлено: май 2026. Версия MCP Python SDK: 1.27.1