# Как создать MCP-сервер: начало работы на Python и TypeScript

> Как создать первый MCP-сервер на Python или TypeScript: требования, установка, код сервера, структура проекта и тестирование в MCP Inspector

Страница: https://mcpdoc.ru/guides/getting-started/
Указатель сайта: https://mcpdoc.ru/llms.txt

Model Context Protocol (MCP) позволяет создавать серверы, которые расширяют возможности AI-ассистентов. В этом руководстве мы создадим первый MCP сервер с нуля.

```mermaid
flowchart LR
    subgraph Client["AI Клиент"]
        Claude[Claude Desktop]
        VSCode[VS Code]
        Cursor[Cursor]
    end

    subgraph Server["MCP Сервер"]
        Tools[Tools<br/>Функции]
        Resources[Resources<br/>Данные]
        Prompts[Prompts<br/>Шаблоны]
    end

    Client <-->|JSON-RPC| Server
```

## Требования

- **Python 3.10+** или **Node.js 18+**
- **pip** или **npm/pnpm**
- **Claude Desktop** или другой MCP клиент для тестирования

## Выбор языка

| Язык | Рекомендуется для | SDK |
|------|-------------------|-----|
| Python | Новичков, ML/Data Science | FastMCP |
| TypeScript | Web-разработчиков | @modelcontextprotocol/sdk |
| PHP | Legacy систем, Laravel | php-mcp/server |
| Rust | Рабочей среды, высокой производительности | rust-sdk |
| Go | Микросервисов | mcp-go |
| C# | .NET экосистемы | modelcontextprotocol |

## Быстрый старт с Python

### 1. Установка

```bash title="Terminal"
# Создание виртуального окружения
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# Установка MCP SDK
pip install mcp
```

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

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

```python title="server.py"
from mcp.server.fastmcp import FastMCP

# Инициализация сервера
mcp = FastMCP("Мой первый сервер")

# Инструмент: функция, которую AI может вызвать
@mcp.tool()
def calculate(operation: str, a: float, b: float) -> float:
    """
    Выполняет математическую операцию.

    Args:
        operation: Операция (add, subtract, multiply, divide)
        a: Первое число
        b: Второе число

    Returns:
        Результат вычисления
    """
    match operation:
        case "add":
            return a + b
        case "subtract":
            return a - b
        case "multiply":
            return a * b
        case "divide":
            if b == 0:
                raise ValueError("Деление на ноль")
            return a / b
        case _:
            raise ValueError(f"Неизвестная операция: {operation}")

# Ресурс: данные, которые AI может прочитать
@mcp.resource("info://server")
def get_server_info() -> str:
    """Информация о сервере"""
    return """
    Сервер: Мой первый MCP сервер
    Версия: 1.0.0
    Автор: kaktak.net
    """

# Промпт: шаблон для структурированных запросов
@mcp.prompt()
def math_prompt(problem: str) -> str:
    """Промпт для математических задач"""
    return f"""
    Реши следующую математическую задачу, используя инструмент calculate:

    {problem}

    Покажи пошаговое решение.
    """

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

### 3. Тестирование с MCP Inspector

[MCP Inspector](https://github.com/modelcontextprotocol/inspector) — официальный инструмент для тестирования серверов:

```bash title="Terminal"
# Установка
npm install -g @anthropic-ai/mcp-inspector

# Запуск
npx @modelcontextprotocol/inspector python server.py
```

Откройте http://localhost:5173 в браузере и протестируйте:
- Вкладка **Tools** — вызовите `calculate`
- Вкладка **Resources** — прочитайте `info://server`
- Вкладка **Prompts** — используйте `math_prompt`

### 4. Подключение к Claude Desktop

Отредактируйте конфигурацию Claude Desktop:

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

```json title="claude_desktop_config.json"
{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["/полный/путь/к/server.py"]
    }
  }
}
```

Перезапустите Claude Desktop. Сервер появится в списке доступных.

## Быстрый старт с TypeScript

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

```bash title="Terminal"
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 title="src/index.ts"
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

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

// Регистрация инструмента
server.tool(
  "calculate",
  {
    operation: { type: "string", enum: ["add", "subtract", "multiply", "divide"] },
    a: { type: "number" },
    b: { type: "number" },
  },
  async ({ operation, a, b }) => {
    let result: number;

    switch (operation) {
      case "add":
        result = a + b;
        break;
      case "subtract":
        result = a - b;
        break;
      case "multiply":
        result = a * b;
        break;
      case "divide":
        if (b === 0) throw new Error("Деление на ноль");
        result = a / b;
        break;
      default:
        throw new Error(`Неизвестная операция: ${operation}`);
    }

    return {
      content: [{ type: "text", text: `Результат: ${result}` }],
    };
  }
);

// Запуск сервера
const transport = new StdioServerTransport();
await server.connect(transport);
```

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

```bash title="Terminal"
npx tsc
node dist/index.js
```

### 4. Конфигурация Claude Desktop

```json title="claude_desktop_config.json"
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/полный/путь/к/dist/index.js"]
    }
  }
}
```

## Структура проекта

Рекомендуемая структура для MCP сервера:

```
my-mcp-server/
├── src/
│   ├── index.ts          # Entry point
│   ├── tools/            # Инструменты
│   │   ├── calculator.ts
│   │   └── filesystem.ts
│   ├── resources/        # Ресурсы
│   │   └── config.ts
│   └── prompts/          # Промпты
│       └── templates.ts
├── tests/
│   └── server.test.ts
├── package.json
├── tsconfig.json
├── Dockerfile            # Для Docker развёртывания
└── README.md
```

## Ключевые концепции

### Инструменты (Tools)

Инструменты — это функции, которые AI может вызывать. Каждый инструмент имеет:
- **Имя** — уникальный идентификатор
- **Описание** — что делает инструмент (важно для AI)
- **Схему параметров** — типы входных данных
- **Обработчик** — логика выполнения

```python title="tools.py"
@mcp.tool()
def search_database(query: str, limit: int = 10) -> list[dict]:
    """
    Поиск в базе данных.

    Args:
        query: Поисковый запрос
        limit: Максимальное количество результатов
    """
    # Логика поиска
    return results
```

### Ресурсы (Resources)

Ресурсы — это данные, которые AI может прочитать:
- **URI** — уникальный идентификатор (`file://`, `db://`, `api://`)
- **MIME-тип** — формат данных
- **Содержимое** — сами данные

```python title="resources.py"
@mcp.resource("config://database")
def get_db_config() -> str:
    """Конфигурация базы данных"""
    return json.dumps({
        "host": "localhost",
        "port": 5432,
        "database": "myapp"
    })
```

### Промпты (Prompts)

Промпты — шаблоны для структурированных запросов:

```python title="prompts.py"
@mcp.prompt()
def code_review(language: str, code: str) -> str:
    """Промпт для ревью кода"""
    return f"""
    Проведи код-ревью следующего {language} кода:

    ```{language}
    {code}
    ```

    Обрати внимание на:
    1. Потенциальные баги
    2. Производительность
    3. Читаемость
    4. Best practices
    """
```

## Следующие шаги

После первого сервера пройдите [официальное руководство по созданию сервера](https://modelcontextprotocol.io/docs/develop/build-server) и посмотрите, как устроены [эталонные серверы проекта](https://github.com/modelcontextprotocol/servers). На этом сайте дальше пригодятся:

- [Python SDK](https://mcpdoc.ru/sdk/python/) — подробная документация FastMCP
- [TypeScript SDK](https://mcpdoc.ru/sdk/typescript/) — работа с Node.js
- [Docker развёртывание](https://mcpdoc.ru/deployment/docker/) — контейнеризация
- [Безопасность](https://mcpdoc.ru/security/best-practices/) — защита сервера