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

Разбираем, как создать MCP сервер на Python и TypeScript с нуля: установка, первый инструмент, подключение к Claude. Практический гайд с командами.
# Как создать 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
```

> **Важно.** Режим `mcp dev` запускает встроенный MCP Inspector — веб-интерфейс для тестирования инструментов без подключения к Claude. Используйте его перед интеграцией.

### Шаг 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 |

> **Важно.** Claude for Desktop читает конфигурацию при запуске. После добавления нового сервера перезапустите приложение полностью.

---

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