graylog-mcp

🔍 Model Context Protocol (MCP) сервер для интеграции Graylog с AI-ассистентами

Минималистичный MCP сервер, предоставляющий инструменты для поиска логов в Graylog через stdio протокол. Работает с Cursor, Claude Desktop и другими MCP-клиентами.

✨ Особенности

• 🚀 Три мощных инструмента для поиска логов
• 🔒 Поддержка Personal Access Token (PAT) аутентификации
• 🌐 Работа с self-signed TLS сертификатами
• 📦 Простая установка через npm/npx
• 🎯 Автоматическая нормализация полей логов
• 🔍 Умный поиск по UUID/trace ID/request ID

📋 Требования

• Node.js >= 18
• Graylog сервер с настроенным Personal Access Token

📦 Установка

Глобальная установка

npm i -g @alexbuzo/graylog-mcp

Использование через npx (рекомендуется)

Не требует установки - см. раздел "Настройка в Cursor"

🚀 Быстрый старт

Запуск вручную

graylog-mcp \
  --graylog-url https://graylog.example.com \
  --token YOUR_GRAYLOG_PAT \
  --ssl-verify=false

Параметры командной строки

Параметр	Обязательный	Описание	По умолчанию
--graylog-url	✅	URL вашего Graylog сервера	-
--token	✅	Personal Access Token	-
--ssl-verify	❌	Проверка SSL сертификата	true
--debug	❌	Режим отладки	false

🔌 Настройка в Cursor

Настройки → MCP Servers → Add custom server

Вариант 1: Через npx (рекомендуется)

{
  "mcpServers": {
    "graylog": {
      "command": "npx",
      "args": [
        "-y",
        "@alexbuzo/graylog-mcp@latest",
        "--graylog-url", "https://graylog.example.com",
        "--token", "YOUR_GRAYLOG_PAT",
        "--ssl-verify", "false"
      ],
      "name": "Graylog Search"
    }
  }
}

Вариант 2: С переменными окружения (безопаснее)

{
  "mcpServers": {
    "graylog": {
      "command": "bash",
      "args": [
        "-lc",
        "npx -y @alexbuzo/graylog-mcp@latest --graylog-url \"$GRAYLOG_URL\" --token \"$GRAYLOG_TOKEN\" --ssl-verify=false"
      ],
      "env": {
        "GRAYLOG_URL": "https://graylog.example.com",
        "GRAYLOG_TOKEN": "YOUR_GRAYLOG_PAT"
      },
      "name": "Graylog (secure)"
    }
  }
}

Вариант 3: Глобальная установка

{
  "mcpServers": {
    "graylog": {
      "command": "graylog-mcp",
      "args": [
        "--graylog-url", "https://graylog.example.com",
        "--token", "YOUR_GRAYLOG_PAT",
        "--ssl-verify", "false"
      ],
      "name": "Graylog"
    }
  }
}

🛠 Доступные инструменты

1. graylog.search_logs

Поиск логов с использованием Lucene/GELF запросов.

Параметры:

• query (string, обязательный): Lucene/GELF запрос
• rangeSec (number, по умолчанию 3600): Временной диапазон в секундах
• limit (number, опционально): Максимальное количество результатов (макс. 500)
• offset (number, опционально): Смещение для пагинации
• filter (string, опционально): Дополнительный фильтр (например, stream:<STREAM_ID>)

Пример запроса:

{
  query: "level:ERROR AND service:api",
  rangeSec: 3600,
  limit: 100,
  filter: "stream:507f1f77bcf86cd799439011"
}

2. graylog.search_uuid

Умный поиск по UUID, request ID, trace ID и другим идентификаторам. Автоматически проверяет множество распространенных полей.

Параметры:

• uuid (string, обязательный): UUID или идентификатор для поиска
• rangeSec (number, по умолчанию 86400): Временной диапазон в секундах (24 часа)
• limit (number, опционально): Максимальное количество результатов (макс. 500)

Автоматически ищет в полях:

• request_id, requestId, req_id
• trace_id, traceId, trace.id
• span_id, spanId, span.id
• transaction_id, transactionId
• correlation_id, correlationId
• _id

Пример запроса:

{
  uuid: "550e8400-e29b-41d4-a716-446655440000",
  rangeSec: 86400,
  limit: 200
}

3. graylog.search_stream

Получение сообщений из конкретного потока (stream).

Параметры:

• streamId (string, обязательный): ID потока в Graylog
• rangeSec (number, по умолчанию 3600): Временной диапазон в секундах
• limit (number, опционально): Максимальное количество результатов (макс. 500)

Пример запроса:

{
  streamId: "507f1f77bcf86cd799439011",
  rangeSec: 7200,
  limit: 150
}

📊 Формат ответа

Все инструменты возвращают нормализованный JSON со следующей структурой:

{
  "total": 42,
  "messages": [
    {
      "id": "message_id",
      "ts": "2024-01-15T10:30:00.000Z",
      "level": "ERROR",
      "source": "api-server-01",
      "container": "api-service",
      "message": "Database connection failed",
      "short_message": "DB error",
      "http_method": "POST",
      "url": "/api/users",
      "status": 500,
      "latency_ms": 1234,
      "trace_id": "abc123",
      "span_id": "def456",
      "request_id": "req-789",
      "tenant_id": "tenant-001",
      "client_ip": "192.168.1.1",
      "user_agent": "Mozilla/5.0...",
      "service": "user-api",
      "request": {...},
      "response": {...}
    }
  ]
}

Автоматическая нормализация полей

Сервер автоматически извлекает и нормализует следующие поля из различных форматов:

Поле	Альтернативные имена
container	container_name, kubernetes.container_name
http_method	method, http_method, request_method
url	path, request_path
status	http_status, response_status
latency_ms	duration_ms, response_time_ms
trace_id	traceId, trace.id
span_id	spanId, span.id
request_id	req_id, requestId
client_ip	remote_addr, ip
service	service_name, app

💻 Локальная разработка

Установка зависимостей

npm install

Сборка проекта

npm run build

Запуск в режиме разработки

npm run dev -- --graylog-url https://graylog.example.com --token YOUR_PAT --ssl-verify=false

Тестирование собранной версии

node dist/cli.js --graylog-url https://graylog.example.com --token YOUR_PAT --ssl-verify=false --debug

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

graylog-mcp/
├── src/
│   ├── cli.ts        # CLI интерфейс и точка входа
│   ├── server.ts     # MCP сервер и регистрация инструментов
│   └── graylog.ts    # API клиент для Graylog
├── dist/             # Скомпилированный код
├── package.json      # Метаданные и зависимости
└── tsconfig.json     # Конфигурация TypeScript

🔒 Безопасность

Personal Access Token (PAT)

1. Создайте PAT в Graylog: System → Users → [Your User] → Edit → Create Token
2. Токен должен иметь права на чтение целевых потоков
3. Сервер автоматически пробует два формата авторизации:
   • token:YOUR_PAT
   • YOUR_PAT:token

SSL/TLS

• Production: Используйте валидный CA сертификат и --ssl-verify=true
• Development/Self-signed: Используйте --ssl-verify=false
• Альтернатива: Установите NODE_EXTRA_CA_CERTS на путь к доверенному CA

Рекомендации

• ✅ Используйте переменные окружения для токенов
• ✅ Не коммитьте токены в git
• ✅ Используйте минимально необходимые права для PAT
• ✅ Регулярно ротируйте токены

🐛 Устранение неполадок

401/403 ошибки

• Проверьте валидность PAT
• Убедитесь, что у токена есть права на чтение потоков
• Проверьте формат URL (должен включать протокол: https://)

TLS/SSL ошибки

# Опция 1: Отключить проверку (не для production!)
--ssl-verify=false

# Опция 2: Указать CA сертификат
export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

Нет результатов

• Попробуйте простой запрос: query: "*"
• Проверьте временной диапазон (увеличьте rangeSec)
• Убедитесь, что в выбранных потоках есть данные
• Проверьте синтаксис Lucene запроса

Debug режим

Запустите с флагом --debug для диагностики:

graylog-mcp --graylog-url ... --token ... --debug

🤝 Примеры использования

Пример 1: Поиск ошибок за последний час

// Инструмент: graylog.search_logs
{
  query: "level:ERROR",
  rangeSec: 3600
}

Пример 2: Поиск по trace ID

// Инструмент: graylog.search_uuid
{
  uuid: "abc-123-def-456",
  rangeSec: 86400
}

Пример 3: Получение логов конкретного сервиса

// Инструмент: graylog.search_logs
{
  query: "service:auth-api AND level:WARN",
  rangeSec: 7200,
  limit: 50
}

Пример 4: Поиск HTTP 5xx ошибок

// Инструмент: graylog.search_logs
{
  query: "status:[500 TO 599]",
  rangeSec: 3600
}

📝 Примечания

• Сервер использует Graylog REST API через /api/search/universal/relative и /api/streams/{id}/messages
• Максимальное количество результатов на запрос: 500
• По умолчанию возвращается 150 записей
• Поддерживается пагинация через параметры limit и offset
• Все временные метки в UTC

🔗 Полезные ссылки

• Model Context Protocol
• Graylog API Documentation
• Lucene Query Syntax

📄 Лицензия

MIT © Aliaksei Buzo

🙏 Вклад

Contributions приветствуются! Пожалуйста, создайте issue или pull request в GitHub репозитории.