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

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

В этом гайде разберём два пути: Python (FastMCP) и TypeScript (MCP SDK). Оба официальных варианта, оба рабочие.

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

MCP сервер — это процесс, который объявляет набор инструментов (tools), ресурсов (resources) и промптов (prompts). Хост (например, Claude for Desktop) подключается к серверу и может вызывать эти инструменты в ходе диалога.

КонцепцияЧто делает
ToolФункция, которую модель может вызвать (поиск, запрос к API)
ResourceДанные, которые модель может прочитать (файл, БД)
PromptШаблон сообщения для типовых сценариев

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

Шаг 1. Установка окружения

Официальный способ — использовать uv для управления зависимостями.

bash
# Установить uv (если ещё нет)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Создать новый проект
uv init my-mcp-server
cd my-mcp-server

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

Альтернатива через pip:

bash
pip install 'mcp[cli]<2'

Шаг 2. Создание сервера

Создайте файл 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.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """Возвращает приветствие"""
    return f"Привет, {name}!"

Шаг 3. Запуск сервера

bash
# Запуск в режиме разработки (с инспектором)
mcp dev server.py

# Запуск через uv
uv run mcp dev server.py

# Запуск с Streamable HTTP транспортом
mcp run server.py --transport streamable-http

Шаг 4. Установка в Claude for Desktop

bash
mcp install server.py

Команда автоматически добавит сервер в конфигурацию Claude for Desktop.

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

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

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

Шаг 2. Создание сервера

Создайте файл src/index.ts:

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

// Создаём сервер
const server = new McpServer({
  name: "my-server",
  version: "1.0.0",
});

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

// Запускаем через stdio транспорт
const transport = new StdioServerTransport();
await server.connect(transport);

Шаг 3. Сборка и запуск

bash
# Сборка
npx tsc

# Запуск
node dist/index.js

Для использования через npx без установки добавьте в package.json:

json
{
  "bin": {
    "my-mcp-server": "./dist/index.js"
  }
}

Шаг 4. Регистрация в Claude Code

Добавьте сервер в конфигурацию Claude Code:

bash
claude mcp add my-server -- node /absolute/path/to/dist/index.js

Готовые примеры серверов

Официальные reference-серверы можно запустить без установки:

bash
# TypeScript-серверы через npx
npx @modelcontextprotocol/server-filesystem /path/to/dir
npx @modelcontextprotocol/server-github

# Python-серверы через uvx
uvx mcp-server-git
uvx mcp-server-fetch

Это удобный способ изучить структуру реального MCP сервера перед написанием своего.

Типичные ошибки

ОшибкаПричинаРешение
`ModuleNotFoundError: mcp`SDK не установлен в активном окруженииЗапускайте через `uv run` или активируйте venv
Сервер не появляется в ClaudeНеверный путь в конфигеИспользуйте абсолютный путь к файлу
`Tool not found`Опечатка в имени инструментаПроверьте имя через MCP Inspector
Сервер падает при стартеСинтаксическая ошибка в кодеЗапустите `mcp dev` — он покажет traceback
Нет ответа от инструментаИнструмент не возвращает правильный типУбедитесь, что возвращаете строку или dict

FAQ

Какой язык выбрать — Python или TypeScript?

Если вы работаете с данными, ML-библиотеками или уже пишете на Python — берите FastMCP. Если строите веб-интеграции или хотите публиковать сервер через npm — TypeScript удобнее.

Можно ли запустить MCP сервер как HTTP-эндпоинт?

Да. FastMCP поддерживает Streamable HTTP транспорт: запустите с флагом --transport streamable-http. Это нужно для удалённых серверов; локальные обычно работают через stdio.

Как протестировать сервер без Claude?

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

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

Технических ограничений нет. На практике рекомендуется группировать связанные инструменты в один сервер, а не создавать по серверу на каждый инструмент.

Как передать API-ключи в сервер безопасно?

Используйте переменные окружения. В конфигурации Claude for Desktop можно указать env-блок с нужными переменными — они будут переданы процессу сервера при запуске.

Источники

  • https://modelcontextprotocol.org/examples
  • https://pypi.org/project/mcp/1.29.0/
  • https://ts.sdk.modelcontextprotocol.io/v2/
  • https://modelcontextprotocol.io/docs/2026-07-28/develop/build-server.md
  • https://modelcontextprotocol.io/docs/2024-11-05/develop/build-server
  • https://www.strayspark.studio/blog/build-mcp-server-game-development-2026
  • https://github.com/kaianuar/mcp-server-guide