Урок 2: Настройка MCP-серверов

Чему вы научитесь

После этого урока вы сможете:

• Установить и настроить MCP-серверы в Claude Code
• Отредактировать конфигурационный файл ~/.claude.json или .mcp.json
• Создать собственный простой MCP-сервер на Python
• Протестировать и отладить MCP-подключения

Содержание

Где хранится конфигурация MCP?

MCP-серверы в Claude Code настраиваются в нескольких файлах в зависимости от уровня:

Глобальная конфигурация (для всех проектов):
~/.claude.json

Для конкретного проекта:
.mcp.json  (в корне проекта)

Структура конфигурации

Пример ~/.claude.json (глобальный) или .mcp.json (проектный):

flowchart LR
  S["~/.claude.json\nили .mcp.json"] --> CC["Claude Code"]
  CC --> MS["MCP серверы"]
  MS --> T["Инструменты"]
  T --> R["Результат"]

Структура конфигурационного файла

Вот как выглядит полная конфигурация ~/.claude.json или .mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/projects"
      ]
    },
    "github": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    "postgres": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-postgres"
      ],
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost/dbname"
      }
    }
  }
}

Что здесь что:

• mcpServers — основной блок со всеми серверами
• filesystem, github, postgres — имена серверов (уникальные ключи)
• command — что запускать (обычно npx)
• args — аргументы команды (какой пакет и его параметры)
• env — переменные окружения (токены, пароли)

Установка MCP-серверов

1. Filesystem (работа с файлами)

# Установка через npm
npx @modelcontextprotocol/server-filesystem

# Добавьте в ~/.claude.json (глобально) или .mcp.json (для проекта):
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname",
        "/tmp"
      ]
    }
  }
}

Что это даст:

• read_file(path) — прочитать файл
• write_file(path, content) — написать файл
• delete_file(path) — удалить файл
• list_directory(path) — список файлов в папке
• search_files(pattern) — поиск по файлам

2. GitHub (работа с репозиториями)

# Сначала получите токен на https://github.com/settings/tokens
# Нужны scope: repo, workflow, admin:org_hook

# Добавьте в ~/.claude.json или .mcp.json:
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}

Что это даст:

• search_repositories(query) — поиск репо
• get_issue(owner, repo, issue_number) — информация об issue
• create_issue(owner, repo, title, body) — создать issue
• create_pull_request(owner, repo, ...) — создать PR
• list_commits(owner, repo) — список коммитов

3. PostgreSQL (работа с БД)

# Убедитесь, что у вас установлен PostgreSQL

# Добавьте в ~/.claude.json или .mcp.json:
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-postgres"
      ],
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost:5432/mydb"
      }
    }
  }
}

Что это даст:

• query(sql) — выполнить SQL-запрос
• list_tables() — список таблиц
• describe_table(name) — описание таблицы

Проверка установки

После добавления серверов в конфиг перезагрузите Claude Code и проверьте:

/mcp list

Должны увидеть:

MCP Servers (3):
  [+] filesystem - 5 tools
  [+] github - 6 tools
  [+] postgres - 3 tools

Создание собственного MCP-сервера на Python

Теперь создадим свой MCP-сервер с помощью FastMCP.

Установка FastMCP

pip install fastmcp

Пример 1: Простой сервер поиска в документах

# my_tools_server.py
from fastmcp import FastMCP

# Создаём новый MCP-сервер
mcp = FastMCP("documentation-search")

# Вспомогательные данные
DOCS = {
    "installation": "Установка: pip install mypackage",
    "getting_started": "Начинаем работу: python -m mypackage",
    "api_reference": "API: читай docs/api.md",
    "troubleshooting": "Проблемы? Смотри FAQ в docs/faq.md"
}

# Инструмент 1: поиск документации
@mcp.tool()
def search_docs(query: str) -> str:
    """Поиск в документации по ключевому слову.
    
    Args:
        query: ключевое слово для поиска
        
    Returns:
        результаты поиска или 'не найдено'
    """
    query_lower = query.lower()
    results = []
    
    for title, content in DOCS.items():
        if query_lower in content.lower() or query_lower in title:
            results.append(f"[{title}] {content}")
    
    return "\n".join(results) if results else "Ничего не найдено"

# Инструмент 2: получить весь список документов
@mcp.tool()
def list_docs() -> str:
    """Список всех доступных документов."""
    return "\n".join(f"- {title}" for title in DOCS.keys())

# Инструмент 3: получить конкретный документ
@mcp.tool()
def get_doc(name: str) -> str:
    """Получить полное содержимое документа.
    
    Args:
        name: название документа (используй list_docs())
        
    Returns:
        содержимое или ошибка
    """
    if name in DOCS:
        return DOCS[name]
    return f"Документ '{name}' не найден. Доступные: {', '.join(DOCS.keys())}"

# Запуск сервера
if __name__ == "__main__":
    mcp.run()

Пример 2: Сервер для работы с внешним API

# weather_server.py
from fastmcp import FastMCP
import requests

mcp = FastMCP("weather-service")

@mcp.tool()
def get_weather(city: str, units: str = "metric") -> str:
    """Получить погоду для города.
    
    Args:
        city: название города
        units: 'metric' (Цельсий) или 'imperial' (Фаренгейт)
        
    Returns:
        информация о погоде
    """
    try:
        # Используем Open-Meteo (бесплатный API)
        url = "https://geocoding-api.open-meteo.com/v1/search"
        params = {"name": city, "count": 1, "language": "en", "format": "json"}
        
        # Получаем координаты города
        geo_resp = requests.get(url, params=params)
        if not geo_resp.json().get("results"):
            return f"Город '{city}' не найден"
        
        result = geo_resp.json()["results"][0]
        lat, lon = result["latitude"], result["longitude"]
        
        # Получаем погоду
        weather_url = "https://api.open-meteo.com/v1/forecast"
        weather_params = {
            "latitude": lat,
            "longitude": lon,
            "current": "temperature_2m,weather_code,wind_speed_10m",
            "temperature_unit": "celsius" if units == "metric" else "fahrenheit"
        }
        
        weather_resp = requests.get(weather_url, params=weather_params)
        current = weather_resp.json()["current"]
        
        return f"Погода в {city}: {current['temperature_2m']}°, ветер {current['wind_speed_10m']} м/с"
    except Exception as e:
        return f"Ошибка: {e}"

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

Регистрация пользовательского сервера

После создания сервера добавьте его в ~/.claude.json или .mcp.json:

{
  "mcpServers": {
    "my-docs": {
      "command": "python",
      "args": ["/Users/yourname/my_tools_server.py"]
    },
    "weather": {
      "command": "python",
      "args": ["/Users/yourname/weather_server.py"]
    }
  }
}

Тестирование и отладка

1. Проверить синтаксис конфига

# На macOS/Linux
cat ~/.claude.json | python -m json.tool

Если JSON некорректный, увидите ошибку.

2. Проверить логи Claude Code

# macOS
tail -f ~/Library/Logs/claude-code/mcp.log

# Linux
tail -f ~/.local/share/claude-code/logs/mcp.log

3. Протестировать сервер вручную

# Запустить сервер отдельно
python my_tools_server.py

# В другом терминале: проверить, что слушает
lsof -i :3000  # если сервер запускается на порту 3000

4. Использовать в Claude Code

Попробуй найти документацию про "installation"

Если сервер подключен правильно, агент должен вызвать инструмент search_docs.

Таблица: популярные команды установки

Попробуйте сами

1. Отредактируйте ~/.claude.json (глобальная конфигурация)

   nano ~/.claude.json

   Или создайте .mcp.json в корне конкретного проекта для проектной конфигурации.

2. Добавьте filesystem-сервер

   {
     "mcpServers": {
       "filesystem": {
         "command": "npx",
         "args": ["@modelcontextprotocol/server-filesystem", "/Users/yourname"]
       }
     }
   }

3. Сохраните (Ctrl+O, Enter, Ctrl+X)

4. Перезагрузите Claude Code

5. Проверьте

   /mcp list

6. Попробуйте

   Прочитай файл ~/README.md

Ключевые выводы

• Конфигурация MCP хранится в ~/.claude.json (глобально) или .mcp.json (для проекта)
• Структура: mcpServers → сервер → command, args, env
• Установка: просто добавьте нужный сервер в конфиг, Claude Code сам установит
• Пользовательские серверы: создавайте на Python с FastMCP — это просто
• Отладка: проверяйте синтаксис JSON, смотрите логи, тестируйте вручную
• Переменные окружения: используйте для токенов и паролей, не пишите их в args

Следующий урок

Урок 3: Топ MCP-серверов — обзор 10 самых полезных готовых MCP-серверов для разработчика.