mcp-server-graylog
Model Context Protocol (MCP) server for Graylog log searching. Search logs by absolute/relative timestamps, filter by streams, and debug production issues directly from Claude Desktop.
Built for production debugging - Search Graylog logs using exact timestamps, filter by application streams, and get actionable insights for troubleshooting production issues.
Features
- ✅ Absolute timestamp search - Debug specific errors with exact time ranges
- ✅ Relative timestamp search - Search recent logs (last N seconds)
- ✅ Distributed tracing - Follow a
trace_id across all services
- ✅ Surrounding-log context - See what happened ±N seconds around an error
- ✅ Composite incident analysis - One tool call fans out to trace + context + baseline
- ✅ Field aggregation - Group counts by service/level/pod/lead_id with bandwidth-efficient projection
- ✅ Stream discovery - List all available streams/applications
- ✅ System health check - Verify Graylog connectivity
- ✅ Comprehensive validation - ISO 8601 timestamps, query syntax, stream IDs
- ✅ Clear error messages - Actionable errors for auth, network, and API issues
- ✅ Timeout handling - 30-second timeouts prevent hanging
- ✅ Production-ready - 54 tests, 9.2/10 code quality score
Table of Contents
Installation
Option 1: Use with npx (Recommended)
# No installation needed - use directly with npx
npx mcp-server-graylog
Option 2: Global Installation
npm install -g mcp-server-graylog
Option 3: Local Installation
# Clone the repository
git clone https://github.com/Pranavj17/mcp-server-graylog.git
cd mcp-server-graylog
# Install dependencies
npm install
Configuration
Claude Desktop Setup
Add to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Using npx (Recommended)
{
"mcpServers": {
"graylog": {
"command": "npx",
"args": ["-y", "mcp-server-graylog"],
"env": {
"BASE_URL": "https://graylog.example.com",
"API_TOKEN": "your_api_token_here"
}
}
}
}
Using Local Installation
{
"mcpServers": {
"graylog": {
"command": "node",
"args": ["/path/to/mcp-server-graylog/src/index.js"],
"env": {
"BASE_URL": "https://graylog.example.com",
"API_TOKEN": "your_api_token_here"
}
}
}
}
Environment Variables
| Variable | Required | Description |
|---|
BASE_URL | Yes | Graylog server URL (e.g., https://graylog.example.com) |
API_TOKEN | Yes | Graylog API token (username for Basic Auth, password is "token") |
Getting Your Graylog API Token
- Log in to Graylog web interface
- Go to System → Users
- Select your user
- Click Edit tokens
- Create a new token with read permissions
- Copy the token value
Available Tools
1. search_logs_absolute
Search logs using absolute timestamps (from/to). Perfect for debugging errors with specific timestamps from monitoring tools or error tracking systems.
Parameters:
query (required): Search query using Elasticsearch syntaxfrom (required): Start timestamp in ISO 8601 formatto (required): End timestamp in ISO 8601 formatstreamId (optional): Stream ID to filter resultslimit (optional): Maximum results (default: 50, max: 1000)
Example:
{
"query": "\"/api/v1/registrations\" AND \"PUT\"",
"from": "2025-10-23T10:00:00.000Z",
"to": "2025-10-23T11:00:00.000Z",
"streamId": "646221a5bd29672a6f0246d8",
"limit": 100
}
2. search_logs_relative
Search logs using relative time range (e.g., last 15 minutes). Useful for recent log analysis.
Parameters:
query (required): Search query using Elasticsearch syntaxrangeSeconds (optional): Time range in seconds (default: 900 = 15 minutes, max: 86400 = 24 hours)streamId (optional): Stream ID to filter resultslimit (optional): Maximum results (default: 50, max: 1000)
