Как создать MCP-сервер на Python и TypeScript

MCP-сервер публикует для AI-приложения инструменты, ресурсы и шаблоны prompts через единый протокол. Ниже — минимальный рабочий scaffold по спецификации и SDK 2026-07-28.

Python: окружение и зависимость

Нужен Python 3.10+ и MCP SDK 2.0.0 или новее. Удобнее использовать uv:

uv init weather
cd weather
uv venv
.venv\Scripts\activate
uv add mcp[cli]
New-Item weather.py

На macOS/Linux активация выполняется командой source .venv/bin/activate, а файл можно создать через touch weather.py.

Для stdio-сервера нельзя писать логи в stdout: там идут JSON-RPC сообщения MCP. Используйте стандартный logging, который пишет в stderr.

Python: MCPServer и первый tool

from mcp.server import MCPServer

mcp = MCPServer("weather")

@mcp.tool()
async def get_temperature(city: str) -> str:
    """Return demo temperature for a city."""
    data = {"Moscow": -2, "Kazan": -5}
    value = data.get(city)
    if value is None:
        return "City not found"
    return f"{city}: {value} °C"

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

Type hints и docstring превращаются в описание инструмента. Реальный tool должен валидировать ввод, устанавливать timeout для внешнего API и возвращать контролируемую ошибку. Запуск: uv run weather.py.

TypeScript: проект и зависимости

Актуальный серверный пакет — @modelcontextprotocol/server. Нужны Node.js 20+, TypeScript и Zod:

mkdir weather
cd weather
npm init -y
npm install @modelcontextprotocol/server zod
npm install -D @types/node typescript
mkdir src

В package.json укажите "type": "module" и скрипт "build": "tsc". Для TypeScript используйте target ES2022, module и moduleResolution Node16, а output направьте в build.

Старые примеры с импортом Server из @modelcontextprotocol/sdk/server/index.js относятся к прежней ветке SDK. Для нового проекта используйте McpServer из серверного пакета.

TypeScript: McpServer и stdio

import { McpServer } from "@modelcontextprotocol/server";
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";

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

server.registerTool(
  "get_temperature",
  {
    description: "Get demo temperature for a city",
    inputSchema: z.object({ city: z.string().min(1) }),
  },
  async ({ city }) => ({
    content: [{ type: "text", text: `${city}: -2 °C` }],
  }),
);

const transport = new StdioServerTransport();
await server.connect(transport);
console.error("MCP server is running on stdio");

Соберите проект через npm run build и запускайте node build/index.js. В stdio-режиме используйте console.error, а не console.log.

Как проверить и подключить сервер

MCP host запускает локальный stdio-сервер как дочерний процесс. В конфигурации указываются команда и абсолютный путь. Для Python это может быть uv --directory C:\path\weather run weather.py, для TypeScript — node C:\path\weather\build\index.js.

Если сервер не подключается, проверьте по порядку:

1. команда запуска работает из терминала;
2. путь абсолютный и корректно экранирован в JSON;
3. stdout не загрязняется логами;
4. Node-проект действительно собран;
5. host перезапущен после изменения конфигурации;
6. ошибки выводятся в stderr и видны в журнале host.

Первый сервер лучше оставить минимальным: один безопасный tool без секретов и побочных эффектов. После успешного handshake добавляйте внешний API, обработку ошибок и авторизацию.