# Как создать свой MCP сервер: полный практический гайд
Каноническая страница: https://plainews.ru/posts/kak-sozdat-svoy-mcp-server-2026-09-18
Опубликовано: 2026-09-18T06:41:02.282Z

Разбираем, как создать свой MCP сервер на Python и TypeScript: установка SDK, написание первого инструмента, подключение к Claude Desktop и типичные ошибки.
# Как создать свой 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` |
| Java | Spring Boot + MCP Starter | Maven/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" — это ограничение версии из официальной документации, которое предотвращает установку несовместимых релизов.

> **Важно.** STDIO-сервер работает как дочерний процесс клиента. Любой вывод в stdout, кроме JSON-RPC сообщений, приведёт к ошибке парсинга на стороне клиента.

---

## 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