Как создать MCP-сервер на Python за 30 минут в 2026

Чтобы создать MCP-сервер на Python, ставите библиотеку mcp[cli] или fastmcp, пишете обычную функцию, вешаете на нее декоратор @mcp.tool() и запускаете mcp.run(). Все. Дальше сервер подключается к Claude Desktop одной командой, и модель начинает вызывать ваш код как инструмент. Ниже собрали весь путь: от установки uv до рабочего примера с доступом к файловой системе и упаковки в Docker.

Обновлено: июль 2026.

TL;DR. MCP-сервер на Python пишется за 30 минут через фреймворк FastMCP. Один декоратор @mcp.tool() превращает функцию в инструмент, докстринг подсказывает модели, когда его звать. Тест идет через Claude Desktop и MCP Inspector. В статье: установка, код сервера для чтения файлов, настройка под Windows и Docker.

MCP (Model Context Protocol) придумала Anthropic и выложила как открытый стандарт 25 ноября 2024 года. В декабре 2025 спецификацию передали в Linux Foundation, так что теперь это инфраструктура, а не продукт одной компании. Протокол уже понимают Claude, Cursor, VS Code, ChatGPT и почти все агентные фреймворки. Значит, сервер, который вы напишете один раз, заработает сразу везде.

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

MCP-сервер это программа, которая дает языковой модели доступ к вашим инструментам, файлам и API через единый протокол. Модель сама решает, когда вызвать функцию, и получает результат обратно.

MCP-сервер это мост между LLM и внешним миром. Модель по умолчанию не видит ваш диск, базу данных или внутренний API. Сервер отдает ей набор функций (tools), и она вызывает их, когда пользователь просит что-то сделать. Anthropic запустила протокол в конце 2024 года, а к первому кварталу 2026 в реестре набралось больше 2000 реализаций.

Раньше каждую интеграцию писали вручную под конкретный API. Один вендор, один формат, куча кода-переходника. MCP убирает этот зоопарк. Вы описываете инструмент один раз, и его подхватывает любой MCP-клиент: Claude Desktop, Cursor, Windsurf, Copilot в VS Code.

По сути сервер работает как ящик с инструментами. Модель без контекста про локальные данные просто задает наводящие вопросы. С подключенным сервером она берет функцию read_file, выполняет ее и отвечает по факту. Разницу видно сразу: пустой чат превращается в помощника, который реально копается в ваших данных.

Что нужно установить перед стартом?

Нужны три вещи: пакетный менеджер uv, библиотека MCP для Python и Claude Desktop как клиент для теста. Установка занимает пять минут, дальше только код.

Минимальный набор для локального MCP на Python это uv, пакет mcp[cli] или fastmcp, и Claude Desktop. uvзаметно быстрее pip и удобнее подхватывает зависимости при подключении сервера. Claude Desktop бесплатный и на сегодня самый обкатанный MCP-хост, поэтому тестировать проще всего в нем.

Сначала ставим uv. На Windows команда идет в PowerShell, на Mac и Linux в обычный терминал. Дальше создаем проект и добавляем библиотеку.

# создаем папку и виртуальное окружение
uv init mcp-files && cd mcp-files

# ставим MCP SDK с CLI-инструментами
uv add "mcp[cli]"

# либо отдельный фреймворк FastMCP
uv add fastmcp

Небольшой нюанс по версиям. FastMCP 1.0 в свое время влили прямо в официальный MCP Python SDK, так что pip install mcp и pip install fastmcp частично про одно и то же. FastMCP 3.x вышла в январе 2026 и принесла компоненты, провайдеры и гранулярную авторизацию. Если хотите стабильности под прод, многие до сих пор пинят mcp[cli]>=1.25,<2, потому что в SDK v2.0 меняется транспортный слой. Мы в VibeCoderz на новых проектах берем свежую FastMCP, а старое трогаем только при миграции.

Как написать первый MCP-сервер на Python?

Импортируете FastMCP, создаете объект mcp, вешаете @mcp.tool() на функцию, в конце вызываете mcp.run(). Докстринг обязателен: по нему модель понимает, когда звать инструмент.

Базовый MCP-сервер на Python это буквально десяток строк. Создаете сервер, декорируете функцию, запускаете. Все протокольное железо (JSON-RPC 2.0, сериализация, регистрация обработчиков) FastMCP прячет под капот. Вы пишете обычный Python.

from fastmcp import FastMCP

mcp = FastMCP("my-first-server")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Складывает два целых числа и возвращает результат."""
    return a + b

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

Вот тут кроется главный секрет, который новички проскакивают. Докстринг это не украшение. Модель читает именно его, чтобы решить, подходит ли инструмент под запрос пользователя. Плохой докстринг = функцию не вызовут ни разу. Хороший = Claude сам сопоставит фразу «сложи 4 и 7» с вашей add и подставит аргументы.

Типы аргументов тоже работают на вас. Аннотация a: int автоматически превращается в схему, по которой клиент валидирует ввод. Пишете def add(a: int, b: int), и модель уже знает, что оба параметра целые. Никакого ручного описания схемы, все выводится из сигнатуры.

Как сделать MCP-сервер с доступом к файловой системе?

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

MCP filesystem это самый частый первый сервер после калькулятора. Даете модели читать и писать файлы в выделенной папке, и она превращается в ассистента, который ведет заметки, разбирает логи или собирает контекст из ваших документов. Ключевое слово тут «выделенной»: пускать LLM во весь диск опасно.

Ниже рабочий пример. Сервер держит все в папке ~/mcp-files и перед каждой операцией проверяет, что путь не убежал наружу через ../.

import os
from fastmcp import FastMCP

mcp = FastMCP("filesystem-reader")

BASE = os.path.expanduser("~/mcp-files")
os.makedirs(BASE, exist_ok=True)

def _safe(name: str) -> str:
    path = os.path.realpath(os.path.join(BASE, name))
    if not path.startswith(os.path.realpath(BASE)):
        raise ValueError("Путь за пределами рабочей папки запрещен")
    return path

@mcp.tool()
def list_files() -> list[str]:
    """Возвращает список файлов в рабочей папке пользователя."""
    return os.listdir(BASE)

@mcp.tool()
def read_file(filename: str) -> str:
    """Читает текстовый файл из рабочей папки и возвращает его содержимое."""
    with open(_safe(filename), "r", encoding="utf-8") as f:
        return f.read()

@mcp.tool()
def write_note(filename: str, text: str) -> str:
    """Дописывает строку текста в файл. Создает файл, если его нет."""
    with open(_safe(filename), "a", encoding="utf-8") as f:
        f.write(text.strip() + "\n")
    return f"Записал в {filename}"

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

Обратите внимание на пару деталей из практики. Файл открываем в режиме a (append), чтобы дописывать, а не затирать. И логи, если добавите, шлите только в stderr. Стандартный вывод stdout занят транспортом, любой лишний print туда рвет соединение с клиентом. На этом спотыкаются примерно все на третьей итерации.

Чем tools отличаются от resources и prompts?

Tool выполняет действие и может менять данные. Resource это read-only источник, который модель читает как контекст. Prompt это шаблон-заготовка, которая всплывает как слеш-команда.

У MCP три примитива, и путаница между ними частая. Tool это глагол: посчитать, записать, дернуть API. Resource это существительное: схема базы, конфиг, документация, которую модель подтягивает без явного вызова. Prompt это готовый сценарий обращения.

Честная оговорка: не все клиенты поддерживают все три. На момент проверки Claude Desktop в первую очередь дружит с tools, а resources и prompts работают не везде одинаково. Так что если строите под конкретный клиент, начните с инструментов, это самый совместимый путь.

Как подключить локальный MCP-сервер к Claude Desktop?

Одна команда fastmcp install claude-desktop server.py. Она сама пропишет конфиг. Дальше полностью перезапускаете Claude Desktop и ищете иконку молотка в поле ввода.

Подключение локального MCP к Claude Desktop это одна команда. FastMCP сам находит объект сервера в файле и добавляет запись в конфиг, руками ничего править не надо.

fastmcp install claude-desktop server.py

После установки Claude Desktop надо закрыть целиком, не просто окно, а процесс, и открыть заново. Если появилась иконка молотка (🔨) слева в поле ввода, значит инструменты подхватились. Просите «покажи файлы в моей папке», и модель дернет list_files.

Иногда автонастройка не срабатывает, особенно если uv стоит нестандартно. Тогда конфиг правят вручную. Путь к файлу зависит от системы, и здесь важна тема windows mcp: на Windows в путях нужны двойные обратные слэши.

Пример ручной записи для mcp подключения:

{
  "mcpServers": {
    "filesystem-reader": {
      "command": "uv",
      "args": ["run", "C:\\Users\\user\\mcp-files\\server.py"]
    }
  }
}

Если сервер не виден после правки, пропишите абсолютный путь к бинарнику uv вместо короткого uv. На Mac и Linux путь покажет команда which uv, на Windows он обычно в C:\Users\<имя>\.local\bin\uv. Ребят, это работает почти всегда, проблема именно в том, что клиент не находит менеджер пакетов.

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

Через MCP Inspector. Команда npx @modelcontextprotocol/inspector поднимает веб-интерфейс, где видно все инструменты, можно передать аргументы и увидеть живой ответ до подключения к модели.

MCP Inspector это официальный отладчик от Anthropic. Он показывает список инструментов, дает вызвать любой с нужными параметрами и сразу рендерит ответ. Проверять логику удобнее в нем, а не гонять модель туда-сюда.

# запуск инспектора поверх вашего сервера
npx @modelcontextprotocol/inspector uv run server.py

# либо через dev-режим SDK
uv run mcp dev server.py

Открываете вкладку Tools, видите свои функции с описаниями из докстрингов, вводите аргументы, жмете Run Tool. Если данные пришли, инструмент готов. Если пусто или ошибка, чините тут, пока быстро.

Полезная деталь про поведение сервера в stdio. Когда вы запускаете его напрямую командой python server.py, он просто висит и ничего не печатает. Это нормально. Сервер ждет JSON-RPC сообщения на вход, а не выводит приветствие. Многие думают, что зависло, и жмут Ctrl+C. Не пугайтесь пустого экрана.

Лиза: «Раньше я вручную разбирала 15-20 видео ради одной статьи. Написала скрипт, который сам транскрибирует и раскладывает по 15 критериям. Было 4 часа на анализ, стало 5,5 минут. Прикинь, один инструмент, а времени высвобождает вагон.»

Как упаковать MCP-сервер в Docker?

Пишете обычный Dockerfile на базе python, копируете сервер, ставите зависимости. Клиент подключаете через docker run -i --rm в команде запуска. Так сервер работает у любого без установки Python.

Docker mcp решает проблему «у меня работает, у коллеги нет». Вместо инструкции с установкой Python и uv вы отдаете образ, и человек запускает контейнер одной командой. Это то, что реально можно передать в команду или выложить в реестр.

FROM python:3.12-slim
WORKDIR /app
COPY server.py .
RUN pip install "mcp[cli]>=1.25,<2"
CMD ["python", "server.py"]

Собираете образ, а в конфиг клиента вместо пути к скрипту пишете запуск контейнера. Флаг -i держит стандартный ввод открытым для транспорта, --rm удаляет контейнер после остановки.

# сборка
docker build -t my-mcp-server .

# подключение в Claude Code одной командой
claude mcp add files -- docker run -i --rm my-mcp-server

Дальше образ можно запушить в Docker Hub или GitHub Container Registry, и любой подключит ваш сервер без единой строчки Python у себя. Для командной работы это чистый выигрыш. Тема близка DevOps-задачам, так что если крутите инфраструктуру, MCP-сервер в контейнере ложится в привычный воркфлоу.

Сильные и слабые стороны MCP на Python

Сильно: минимум кода, автосхемы из типов, один сервер под все клиенты. Слабо: сырой протокол местами, неровная поддержка resources в клиентах, реальные вопросы безопасности при доступе к файлам.

Сильные стороны видно сразу. Декоратор снимает всю возню с JSON-RPC. Типы Python превращаются в схемы автоматически. Сервер, написанный раз, подходит к Claude, Cursor, VS Code и ChatGPT без переделок. Порог входа честно низкий: рабочая версия это работа на один вечер.

Теперь слабые места, без замалчивания. Протокол молодой, часть вещей приходится фиксить руками, вроде абсолютных путей в конфиге. Клиенты поддерживают resources и prompts неравномерно. И главное: доступ к файловой системе или базе это дыра, если не ограничить. В 2025-2026 по MCP-серверам уже завели реальные CVE. Открывать только нужные операции, для чтения оставлять GET-подобные функции, для чувствительных данных вешать авторизацию по токену.

Частые ошибки при настройке MCP

Три классических грабли: пустой докстринг, print в stdout и клиент не находит uv. Первое ломает вызов инструмента, второе рвет соединение, третье лечится абсолютным путем.

Чаще всего сервер «не работает» по одной из трех причин, и все они бытовые. Собрали их в таблицу, чтобы не гуглить по форумам.

По опыту, 8 из 10 обращений «помогите, MCP настройка не идет» это именно докстринг или незакрытый Claude Desktop. Сначала проверьте эти два, потом уже копайте глубже.

Частые вопросы про MCP-сервер на Python

Обязательно ли использовать FastMCP или можно на голом SDK? Можно на голом, но смысла мало. FastMCP это высокоуровневая обертка внутри официального пакета mcp. Она снимает весь протокольный boilerplate. Голый SDK берут, когда нужен кастомный транспорт или нестандартные сообщения. Для 95% задач FastMCP быстрее.

Работает ли мой сервер с ChatGPT и Cursor, или только с Claude? Работает со всеми. MCP это открытый стандарт, и любой совместимый клиент подключается к вашему серверу. Claude Desktop, Cursor, VS Code с Copilot, ChatGPT через Apps SDK, LM Studio. Пишете один раз, подключаете куда угодно.

Что такое mcp cli и зачем ставить mcp[cli]? Это набор командных утилит внутри SDK. Он дает mcp dev для отладки и интеграцию с Inspector. Ставите uv add "mcp[cli]" и получаете инструменты для локальной проверки сервера без модели.

Локальный MCP это безопасно? Сам протокол безопасен, риски создает то, что вы открываете. Доступ к файлам или базе без ограничений это реальная дыра. Держите сервер в песочнице-папке, проверяйте пути, для записи и удаления данных ставьте токен-авторизацию.

Нужно ли платить за Claude Desktop для теста? Нет. Claude Desktop бесплатный, локальные MCP-серверы через stdio работают на бесплатном тарифе. Удаленные серверы по HTTP в бете доступны на платных планах, но для старта они не нужны.

Где взять готовые MCP-серверы, чтобы не писать с нуля? В реестре mcp.so и на GitHub уже больше 2000 реализаций. Но кастомный сервер под свою задачу почти всегда полезнее готового: вы точно знаете, что он делает и куда лезет.

Глоссарий

MCP (Model Context Protocol) это открытый стандарт от Anthropic для связи языковых моделей с внешними инструментами и данными.

Tool это функция, которую модель вызывает через сервер. Может выполнять действия и менять данные.

Resource это read-only источник данных с адресом-URI, который модель читает как контекст.

Prompt это шаблон запроса, который клиент показывает как готовую слеш-команду.

FastMCP это Python-фреймворк-обертка над MCP SDK. Убирает протокольный код, оставляет декораторы.

stdio это транспорт через стандартный ввод-вывод. Используется для локальных серверов.

MCP Inspector это официальный отладчик Anthropic для проверки инструментов до подключения к модели.

uv это быстрый пакетный менеджер для Python, альтернатива pip.

Docstring это строка документации функции. По ней модель решает, когда вызвать инструмент.

С чего начать прямо сейчас

Соберите калькулятор из первого примера, подключите к Claude Desktop и убедитесь, что молоток появился. Как только увидите, что модель зовет вашу функцию, дальше пойдет само: файловый сервер, потом доступ к API, потом своя бизнес-логика. Первый барьер это просто увидеть, что оно работает.

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

Статья обновлена: июль 2026. Данные по версиям FastMCP, командам и путям конфигов актуальны на момент публикации, проверяйте официальную документацию MCP при обновлении SDK.

<!-- JSON-LD для нейровыдачи. Вставляется в <head> страницы. -->