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

MCP (Model Context Protocol) — открытый протокол от Anthropic, который позволяет языковым моделям обращаться к внешним инструментам и данным через стандартизированный интерфейс. Если вы хотите научиться создавать свой MCP сервер, этот гайд проведёт вас от установки до первого рабочего инструмента.

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

MCP сервер — это программа, которая предоставляет LLM-клиенту (например, Claude Desktop) набор инструментов (tools), ресурсов (resources) и подсказок (prompts). Клиент вызывает их по запросу модели.

Типичные сценарии:

  • подключить базу данных к чат-боту
  • дать модели доступ к вашему внутреннему API
  • автоматизировать работу с файловой системой

Протокол поддерживает два транспорта: STDIO (локальный процесс) и SSE (удалённый HTTP-сервер).

Выбор языка и SDK

ЯзыкSDKУстановка
Python`mcp``pip install "mcp[cli]<2"`
TypeScript / Node.js`@modelcontextprotocol/sdk``npm install @modelcontextprotocol/sdk`
JavaSpring Boot + MCP StarterMaven/Gradle зависимость

Для большинства задач проще всего начать с Python — у него наиболее подробная официальная документация.

Вариант 1: Python MCP сервер

Шаг 1. Создать проект с uv

Официальная документация рекомендует uv как менеджер пакетов.

bash
uv init my-mcp-server
cd my-mcp-server
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

Шаг 2. Установить зависимости

bash
uv add "mcp[cli]" httpx

Или через pip, если не используете uv:

bash
pip install "mcp[cli]<2"

Шаг 3. Написать сервер

Создайте файл server.py:

python
from mcp.server.fastmcp import FastMCP

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

# Регистрация инструмента
@mcp.tool()
def add(a: int, b: int) -> int:
    """Складывает два числа"""
    return a + b

@mcp.tool()
def greet(name: str) -> str:
    """Возвращает приветствие"""
    return f"Привет, {name}!"

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

Шаг 4. Запустить и протестировать

bash
uv run mcp dev server.py

Команда mcp dev запускает встроенный инспектор — браузерный интерфейс для тестирования инструментов без подключения к клиенту.

Шаг 5. Установить сервер в Claude Desktop

bash
mcp install server.py

Команда автоматически добавляет запись в конфигурационный файл Claude Desktop.

Вариант 2: TypeScript MCP сервер

Шаг 1. Инициализировать проект

bash
mkdir my-mcp-ts && cd my-mcp-ts
npm init -y
npm install @modelcontextprotocol/sdk
npm install -D typescript @types/node

Шаг 2. Написать сервер

Создайте файл server.ts:

typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { serveStdio } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "my-ts-server",
  version: "1.0.0",
});

// Регистрация инструмента
server.registerTool(
  "add",
  {
    description: "Складывает два числа",
    inputSchema: {
      a: z.number(),
      b: z.number(),
    },
  },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }],
  })
);

// Запуск через STDIO
serveStdio(server);

Шаг 3. Скомпилировать и запустить

bash
npx tsc
node dist/server.js

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

Если mcp install не подходит, отредактируйте конфиг Claude Desktop напрямую.

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

json
{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["/абсолютный/путь/до/server.py"]
    }
  }
}

После сохранения перезапустите Claude Desktop.

Типичные ошибки и как их избежать

Сервер не появляется в Claude Desktop Проверьте, что путь в конфиге абсолютный, а не относительный. Claude Desktop не знает, из какой директории запускать скрипт.

Сломанные JSON-RPC сообщения при STDIO-транспорте Не используйте print() или console.log() для отладки в STDIO-режиме — вывод в stdout ломает протокол. Пишите логи в stderr или в файл.

python
import sys
print("debug info", file=sys.stderr)  # правильно

Ошибка `ModuleNotFoundError: No module named 'mcp'` Claude Desktop запускает сервер в своём окружении. Укажите полный путь до интерпретатора из вашего venv:

json
{
  "mcpServers": {
    "my-server": {
      "command": "/путь/до/проекта/.venv/bin/python",
      "args": ["/путь/до/проекта/server.py"]
    }
  }
}

Конфликт версий: `mcp` vs `mcp[cli]` Используйте "mcp[cli]<2" — это ограничение версии из официальной документации, которое предотвращает установку несовместимых релизов.

FAQ

Нужно ли разворачивать сервер в облаке?

Нет. Для локального использования с Claude Desktop достаточно STDIO-транспорта — сервер запускается как обычный процесс на вашем компьютере. Облако нужно только если вы хотите дать доступ к серверу другим пользователям или сервисам через SSE.

Можно ли использовать MCP сервер с другими клиентами, не только с Claude?

Да. MCP — открытый протокол. Его поддерживают Cursor, Cline, Continue и другие инструменты. Конфигурация подключения у каждого клиента своя, но сам сервер переписывать не нужно.

Как добавить несколько инструментов в один сервер?

Просто декорируйте несколько функций через @mcp.tool() в одном файле. Все они будут зарегистрированы в одном сервере и видны клиенту как отдельные инструменты.

Чем FastMCP отличается от низкоуровневого Server?

FastMCP — высокоуровневая обёртка, которая автоматически генерирует JSON Schema из аннотаций типов Python и упрощает регистрацию инструментов. Низкоуровневый Server даёт больше контроля, но требует ручного описания схем.

Как отлаживать сервер без Claude Desktop?

Используйте команду uv run mcp dev server.py — она запускает встроенный MCP Inspector с браузерным интерфейсом, где можно вызывать инструменты вручную и смотреть сырые JSON-RPC сообщения.

Источники

  • https://modelcontextprotocol.org/docs/2025-11-25/develop/build-server
  • https://pypi.org/project/mcp/1.10.1/
  • https://pypi.org/project/mcp/1.29.0/
  • https://ts.sdk.modelcontextprotocol.io/v2/index.md
  • https://codewithclaude.net/mcp/building-custom-mcps