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_idtrace_id,traceId,trace.idspan_id,spanId,span.idtransaction_id,transactionIdcorrelation_id,correlationId_id
Пример запроса:
{
uuid: "550e8400-e29b-41d4-a716-446655440000",
rangeSec: 86400,
limit: 200
}
3. graylog.search_stream
Получение сообщений из конкретного потока (stream).
Параметры:
streamId(string, обязательный): ID потока в GraylograngeSec(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)
- Создайте PAT в Graylog: System → Users → [Your User] → Edit → Create Token
- Токен должен иметь права на чтение целевых потоков
- Сервер автоматически пробует два формата авторизации:
token:YOUR_PATYOUR_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
🔗 Полезные ссылки
📄 Лицензия
MIT © Aliaksei Buzo
🙏 Вклад
Contributions приветствуются! Пожалуйста, создайте issue или pull request в GitHub репозитории.