Как создать свой MCP‑сервер: пошаговое руководство

ИИ-ассистенты давно переросли свой имидж «интересной игрушки». Они уверенно становятся полезным рабочим инструментом: помогают писать документацию, анализировать логи и обеспечивать поддержку пользователей. Но есть одно ограничение: пока что модель ещё не умеет работать с вашими внутренними данными и системами. Она не «видит» общего контекста вашей работы и поэтому остаётся всего лишь «умным собеседником», а не полноценным участником процесса.

Model Context Protocol (MCP) помогает решить эту задачу: это открытый стандарт Anthropic, который задаёт единый формат общения между ИИ-клиентами (например, Claude Desktop) и внешними системами (файлами, БД, сервисами, порталами документации). Написав MCP-сервер один раз, вы создаёте точку интеграции, которую может использовать любой MCP-совместимый клиент. При этом вам не придётся создавать отдельный «коннектор» под каждый продукт.

Что такое MCP‑сервер

Представьте себе компанию (назовём её DataHouse), которая предоставляет SaaS-платформу для аналитики розничных продаж. В вашем распоряжении есть мощная внутренняя база данных, где хранятся данные по всем магазинам за последние три года. Команда разработчиков использует ИИ-ассистента для написания сложных аналитических запросов и проверки гипотез о поведении клиентов.

До внедрения MCP рабочий процесс выглядел так: разработчик формулирует задачу для ассистента, например, «Напиши запрос, который покажет динамику среднего чека по регионам за прошлый квартал». ИИ генерирует SQL-код, который выглядит синтаксически верным. Однако когда вы запускаете этот код в реальной среде, возникает ошибка — потому что ассистент не знал, что в вашей внутренней схеме данных поле region называется store_region_code, а поле revenue хранится не в рублях, а в копейках. Ошибка связана с тем, что ассистент работает вне вашего контекста: он не «видит» вашу рабочую среду и не имеет доступа к её содержанию.

Поэтому вам приходится вручную править запрос, запускать его и возвращаться к ассистенту с полученным результатом, чтобы обсудить цифры. Затем вы снова переключаетесь на среду выполнения, чтобы проверить новую гипотезу, снова копируете данные, снова объясняете контекст. Другими словами, человек становится «посредником» («переводчиком») между машинами — корректирует запросы так, чтобы они соответствовали контексту, и передаёт данные.

При таком подходе ИИ остаётся генератором черновиков, а не участником аналитического процесса: каждый новый диалог требует повторного объяснения основных фактов о вашей инфраструктуре, потому что модель сохраняет память только в течение одной сессии.

MCP меняет правила игры. Написав один MCP-сервер, который подключается к вашему DataHouse и умеет выполнять безопасные SELECT-запросы с ограничением по времени и объёму данных, вы даёте ассистенту прямой доступ к вашей реальности. Теперь в том же диалоге вы можете попросить: «Покажи средний чек по Сибири за март». Ассистент вызывает ваш инструмент, получает реальные цифры и уже на их основе строит дальнейший анализ. Вы перестаёте быть «переводчиком» между ИИ и вашей инфраструктурой — ассистент начинает говорить с вашими данными напрямую.

Таким образом, MCP — это идеальный способ «научить» ИИ-клиента общаться с внешними системами. Вместо человека MCP-сервер играет роль «посредника» между моделью и вашими данными и инструментами: он описывает, какие операции доступны, какие параметры они принимают и что возвращают.

MCP-сервер предоставляет три примитива:

• Tools (инструменты) — функции, которые модель может вызвать по запросу пользователя (аналог вызова POST-эндпоинта: есть действие, есть параметры, есть результат).
• Resources (ресурсы) — данные, которые модель может читать без явного «вызова функции» (аналог GET: конфиг, статус системы, содержание документа).
• Prompts (шаблоны) — заранее подготовленные промпты для повторного использования, например стандартный запрос для ревью документа.

По способу работы MCP-серверы бывают:

• Локальные — запускаются на том же компьютере, что и клиент, и общаются через стандартные потоки ввода-вывода (stdio — standard input/output).
• Удалённые — работают в облаке или на удалённом сервере и общаются по HTTP/SSE.

В этой статье мы сосредоточим внимание на локальном варианте: он проще всего для старта, особенно если вы хотите попробовать поработать с MCP и понять, как ИИ-ассистент взаимодействует с вашими инструментами и файлами.

Простую архитектуру, которую мы рассмотрим, можно сформулировать одной строкой: хост (Claude Desktop) → MCP-клиент → MCP-сервер → ваши данные и инструменты.

Если захочется углубиться в спецификацию (типизация, протокол, форматы сообщений), стоит обратиться к официальной документации — там протокол описан подробно и с примерами.

Что потребуется

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

• Python 3.10 или выше.
• uv — менеджер пакетов и виртуальных окружений для Python. Он рекомендуется в примерах MCP-серверов на Python, потому что упрощает изоляцию зависимостей при установке MCP.
• Claude Desktop — приложение для macOS или Windows. На Linux десктопная версия недоступна. Предлагается удобная альтернатива — запуск и отладка MCP-серверов через MCP Inspector в браузере.
• Базовые навыки работы с командной строкой — переход между директориями, запуск команд, редактирование файлов.

Если вы предпочитаете классический стек pip + venv, его можно использовать, но в примере мы будем опираться на uv: так проще повторить шаги и избежать конфликтов зависимостей в разных проектах.

Создание MCP‑сервера: пошаговый процесс

Итак, мы подошли к основной части статьи, в которой опишем практические шаги настройки MCP-сервера и приведём команды с пояснениями.

Шаг 1 — Создание проекта и установка зависимостей

В терминале выполните:

uv init mcp-server-demo

cd mcp-server-demo

uv venv

source .venv/bin/activate # Windows: .venv\Scripts\activate

uv add "mcp[cli]"

Что при этом происходит: uv init mcp-server-demo создаёт новую папку проекта с базовой структурой и файлом pyproject.toml. uv venv создаёт изолированное виртуальное окружение — это защищает проект от конфликтов с глобально установленными пакетами. source .venv/bin/activate (или .venv\Scripts\activate на Windows) активирует окружение: после этого все команды python и uv относятся к текущему проекту. uv add «mcp[cli]» устанавливает Python-SDK для MCP вместе с CLI-утилитой, которая понадобится для локального тестирования через команду mcp dev.

Если вы ведёте несколько Python-проектов параллельно, изолированное окружение избавляет от таких неприятных ситуаций: «обновили библиотеку для одного проекта — сломали другой».

Шаг 2 — Написание сервера

Создайте файл server.py в папке проекта и добавьте в него код:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("demo-server")

@mcp.tool()

def get_current_time() -> str:

    """

    Возвращает текущую дату и время.

    """

    from datetime import datetime

    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")

if __name__ == "__main__":

    mcp.run(transport="stdio")

Обратите внимание на несколько моментов:

• FastMCP — высокоуровневая надстройка над официальным Python-SDK MCP. Она берёт на себя всю работу с протоколом (форматы сообщений, обработка запросов и ответов), оставляя вам только бизнес-логику инструментов. Если вы работали с FastAPI, синтаксис покажется знакомым.
• Декоратор @mcp.tool() регистрирует функцию как инструмент MCP. Claude увидит её в списке доступных tools и сможет вызывать, когда в диалоге возникает подходящий запрос.
• Тройные кавычки внутри функции — это docstring. Для MCP он очень важен: по описанию инструментов модель решает, что именно и когда вызвать. Чем точнее и яснее описание, тем больше шансов, что ИИ выберет правильный инструмент и передаст правильные параметры.
• Вызов mcp.run(transport=»stdio») запускает сервер в режиме общения через стандартные потоки ввода-вывода (stdio). Это стандартный транспорт для локальных MCP-серверов, которые работают вместе с клиентами.

Шаг 3 — Локальное тестирование через MCP Inspector

Прежде чем подключать сервер к Claude Desktop, важно убедиться, что он запускается и инструменты работают. В активированном окружении выполните:

mcp dev server.py

Эта команда запускает ваш MCP-сервер и открывает MCP Inspector в браузере — встроенный интерфейс для тестирования. В MCP Inspector вы можете вручную вызывать инструменты (например, get_current_time), смотреть, какие параметры доступны, и изучать ответы и возможные ошибки.

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

Шаг 4 — Как подключить MCP-сервер к Claude Desktop

Теперь необходимо «объяснить» Claude Desktop, как запускать ваш сервер. Для этого используется конфигурационный файл claude_desktop_config.json.

Стандартные пути:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Если файл ещё не создан, создайте его вручную. Добавьте в него примерно такой блок (обязательно замените путь на абсолютный путь к вашей папке проекта):

{

  "mcpServers": {

    "demo-server": {

      "command": "uv",

      "args": [

        "--directory",

        "/АБСОЛЮТНЫЙ/ПУТЬ/К/ПАПКЕ/mcp-server-demo",

        "run",

        "server.py"

      ]

    }

  }

}

Что здесь важно: в секции mcpServers перечисляются MCP-серверы по имени. В нашем примере это demo-server — то самое имя, которое вы передали в FastMCP. Поле command показывает, какой исполняемый файл использовать (здесь uv). Массив args описывает аргументы командной строки: —directory указывает папку проекта, далее идёт абсолютный путь к проекту, а run и server.py — команда uv для запуска скрипта сервера.

Критически важный момент — абсолютный путь. Относительные варианты, такие как ./mcp-server-demo, не работают: Claude Desktop запускает процесс из своего контекста, и ему нужно точное указание, где находится ваш проект. Ошибка пути — одна из самых частых причин, по которым сервер не появляется в интерфейсе.

После изменения конфигурации полностью закройте Claude Desktop (именно «Quit/Выход», а не просто закройте окно) и запустите приложение заново.

Шаг 5 — Проверка работы в Claude Desktop

После рестарта откройте Claude Desktop. В нижней части окна, рядом с полем ввода, должен появиться значок молотка. Число рядом показывает, сколько MCP-серверов сейчас подключено.

Нажмите на иконку молотка, чтобы открыть перечень доступных инструментов, и убедитесь, что там есть ваш сервер demo-server и инструмент get_current_time. Введите что-то подобное: «Скажи, который сейчас час».

Если интеграция настроена корректно, Claude поймёт, что в вашем сервере есть инструмент, подходящий для этого запроса, вызовет get_current_time и вернёт в ответе текущие дату и время, пришедшие с MCP-сервера.

Таким образом, вы видите полный контур: от пользовательского запроса до вызова вашего кода и возврата.

Расширение сервера: добавление нескольких инструментов

Один инструмент — хорошо, но реальная польза начинается, когда сервер предоставляет набор операций. В FastMCP новый инструмент — это просто ещё одна функция с декоратором @mcp.tool() в том же файле. Никакой дополнительной «регистрации» не требуется: при старте сервера FastMCP автоматически обнаружит все такие функции.

Добавим, например, конвертацию температуры:

@mcp.tool()

def convert_celsius_to_fahrenheit(celsius: float) -> str:

    """

    Конвертирует температуру из Цельсия в Фаренгейт.

    :param celsius: Температура в градусах Цельсия

    """

    fahrenheit = (celsius * 9/5) + 32

    return f"{celsius}°C = {fahrenheit}°F"

Обратите внимание: аннотация celsius: float играет роль не только для читабельности. FastMCP и MCP-клиент используют типы аргументов для генерации схемы параметров (JSON Schema). По этой схеме Claude понимает, какой тип значения нужно передать, и может валидировать ввод. Если убрать типизацию, инструмент может работать непредсказуемо: модель не будет уверена, что именно ожидает функция.

Docstring по-прежнему важен. Хорошая практика — описывать, что делает инструмент, какие параметры принимает и в каких единицах, что возвращает и в каком формате. Для технического писателя это фактически мини-спецификация API, только для ИИ-клиента. Чем лучше она написана, тем стабильнее ведёт себя система.

Типичные ошибки и как их исправить

При первых попытках запускать MCP-серверы возникают очень похожие проблемы:

Отдельно стоит упомянуть безопасность. Локальный MCP-сервер запускается под вашей учётной записью и может получать доступ к локальной файловой системе, переменным окружения и внутренним сервисам — всё зависит от того, какие инструменты вы в него добавите. Подключайте только те серверы, коду которых вы доверяете, не копируйте серверный код из неизвестных источников без проверки, а для корпоративной среды заранее обсудите со службой безопасности, какие ресурсы можно открывать через MCP.

Что дальше

Минимальный сервер — хороший старт, но MCP даёт гораздо больше возможностей.

• Resources. В этой статье мы работали только с инструментами (tools), которые модель вызывает активно. Ресурсы работают иначе: это данные, к которым ИИ может обращаться «по запросу контекста» — например, чтобы прочитать конфигурацию системы, состояние сервиса или содержание документа.
• Удалённые серверы. Локальный stdio-сервер привязан к конкретному компьютеру. Если вам нужен доступ с других устройств, CI/CD, облачного окружения или внутри корпоративной инфраструктуры, можно перейти на HTTP/SSE-транспорт и развернуть сервер в облаке или на отдельном хосте.
• Готовые серверы. Не обязательно всё писать с нуля. Уже существует открытый реестр MCP-серверов от Anthropic и сообщества: файловая система, Git, базы данных, Slack и многие другие сервисы.
• Порталы документации. Например, Документерра реализовала MCP-сервер, который даёт ИИ-агенту доступ ко всему порталу документации: структуре проектов, контенту топиков, поиску.

* * *

MCP снимает главный барьер между ИИ-ассистентом и реальной работой. Он отменяет необходимость каждый раз писать уникальную интеграцию под конкретный сервис или систему. Вместо этого вы один раз создаёте MCP-сервер, описываете доступные инструменты и ресурсы — и любой MCP-совместимый клиент может с ним работать.

Порог входа невысокий: несколько десятков строк кода, один конфигурационный файл и базовые навыки работы с терминалом. Этого достаточно, чтобы Claude увидел ваши инструменты и смог использовать их в диалоге. Дальше всё упирается только в ваши сценарии: от простых утилит до сложных серверов, которые управляют документацией, CI-пайплайнами и внутренними системами компании.

ЧаВо