graylog-log-search

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
• Configuration
• Available Tools
• Skills & agents
• Query Examples
• Troubleshooting
• Development
• Contributing
• License

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

1. Log in to Graylog web interface
2. Go to System → Users
3. Select your user
4. Click Edit tokens
5. Create a new token with read permissions
6. 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 syntax
• from (required): Start timestamp in ISO 8601 format
• to (required): End timestamp in ISO 8601 format
• streamId (optional): Stream ID to filter results
• limit (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 syntax
• rangeSeconds (optional): Time range in seconds (default: 900 = 15 minutes, max: 86400 = 24 hours)
• streamId (optional): Stream ID to filter results
• limit (optional): Maximum results (default: 50, max: 1000)