jaeger-mcp

MCP-сервер для распределенной трассировки Jaeger. Предоставьте Claude (или любому агенту с поддержкой MCP) доступ на чтение к вашим данным трассировки — ищите трассировки, проверяйте спаны, стройте карту зависимостей сервисов — не покидая диалога.

Зачем нужен еще один Jaeger MCP?

Существующие интеграции Jaeger требуют запущенного UI или пользовательских скриптов. Этот сервер:

• Использует стандартный Model Context Protocol через stdio — работает с Claude Desktop, Claude Code, Cursor и любым MCP-клиентом.

• Работает только для чтения: все 5 инструментов содержат readOnlyHint: true — нулевой риск изменения данных трассировки.

• Возвращает двухканальный вывод: структурированный JSON (structuredContent) для программного использования + Markdown (content) для отображения человеку.

• Имеет понятные сообщения об ошибках, которые указывают точную переменную окружения для исправления и предлагают следующий шаг.

• Поддерживает Bearer-токен, HTTP Basic auth или отсутствие авторизации (обычно для внутренних развертываний).

Инструменты

Установка

pip install jaeger-mcp

Или запустите напрямую без установки:

uvx jaeger-mcp

Конфигурация

Вся конфигурация осуществляется через переменные окружения:

Скопируйте .env.example в .env и заполните свои значения.

Настройка Claude Desktop / Claude Code

Добавьте в вашу конфигурацию MCP (claude_desktop_config.json или .claude/mcp.json):

{
  "mcpServers": {
    "jaeger": {
      "command": "jaeger-mcp",
      "env": {
        "JAEGER_URL": "https://jaeger.example.com",
        "JAEGER_TOKEN": "your-token-here"
      }
    }
  }
}

Или с помощью uvx (установка не требуется):

{
  "mcpServers": {
    "jaeger": {
      "command": "uvx",
      "args": ["jaeger-mcp"],
      "env": {
        "JAEGER_URL": "https://jaeger.example.com"
      }
    }
  }
}

Docker

docker run --rm -e JAEGER_URL=https://jaeger.example.com jaeger-mcp

Примеры запросов

После настройки спросите Claude:

• "Какие сервисы известны Jaeger?"

• "Найди трассировки с ошибками HTTP 500 в order-service за последний час"

• "Покажи мне самые медленные трассировки (более 2 секунд) для GET /checkout"

• "Что вызвало ошибку в трассировке abcdef1234567890?"

• "Построй граф зависимостей сервисов за последние 7 дней"

• "Какие сервисы чаще всего вызывают postgres?"

Руководство по использованию инструментов

jaeger_list_services

Возвращает все имена сервисов, которые видел Jaeger. Начните отсюда, если не знаете, какие сервисы инструментированы. Вывод ограничен 500 сервисами с подсказкой об усечении.

jaeger_list_operations

Возвращает все имена операций для заданного сервиса (например, имена HTTP-маршрутов, имена методов gRPC). Используйте для обнаружения допустимых имен операций перед фильтрацией jaeger_search_traces.

jaeger_search_traces

Основной инструмент поиска. Фильтры:

• service (обязательно) — имя сервиса из jaeger_list_services

• operation — сузить до конкретного эндпоинта

• tags — JSON-строка фильтров тегов, например {"http.status_code":"500"} или {"error":"true"}

• start / end — временной диапазон в микросекундах UTC

• min_duration / max_duration — строки длительности, такие как "100ms", "1.5s", "2m"

• limit — по умолчанию 20, максимум 1500

Возвращает сводки трассировок с trace_id, duration_us, span_count, service_count, root_operation, errors_count.

jaeger_get_trace

Полные детали трассировки. Принимает trace_id (шестнадцатеричная строка, 16-32 символа) и возвращает:

• Все спаны с тегами, именами сервисов, отношениями родитель/потомок

• Статистику по сервисам (количество спанов, общая длительность, количество ошибок)

• Дерево выполнения (каждый узел перечисляет ID своих дочерних спанов)

Спаны с ошибками идентифицируются по tags["error"] = "true".

jaeger_get_dependencies

Граф топологии сервисов. Возвращает направленные ребра (родитель → потомок) с call_count. Используйте lookback_hours (по умолчанию 24, максимум 720) для управления окном времени.

Характеристики производительности

• Все инструменты используют единую постоянную requests.Session с пулом соединений.

• Сессия имеет trust_env = False для обхода прокси окружения (Jaeger обычно является внутренним сервисом).

• Запросы имеют тайм-аут 30 секунд.

• jaeger_search_traces передает limit напрямую в Jaeger — избегайте запроса большего количества трассировок, чем необходимо.

• jaeger_get_trace получает полную трассировку за один вызов — большие трассировки (тысячи спанов) могут работать медленно.

• jaeger_get_dependencies агрегирует данные за все окно поиска; большие окна могут работать медленно на загруженных кластерах.

Разработка

git clone https://github.com/mshegolev/jaeger-mcp
cd jaeger-mcp
pip install -e '.[dev]'
pytest tests/ -v
ruff check src tests
ruff format src tests

Лицензия

MIT — см. LICENSE.