GR
Search

Graylog MCP Server: Timestamped Stream Logs for Debugging

Search Graylog logs on the MCP server by absolute or relative timestamps, filter streams, and debug production issues from Claude Desktop.

View on GitHub
Quick Install
npx -y @Pranavj17/mcp-server-graylog

Overview

The Graylog MCP Server exposes timestamped Graylog stream data through a simple HTTP API that conforms to the Model Context Protocol (MCP). It lets language models and debugging tools (for example, Claude Desktop) request logs by absolute timestamp or by relative time ranges, filter by one or more Graylog streams, and receive immediately consumable, structured log context for troubleshooting production issues.

This server is useful when you need reproducible, time-bound slices of production logs for incident analysis or as context fed to an assistant. By supporting absolute and relative timestamps, stream-level filtering, and compact JSON output, the MCP server helps developers quickly gather the minimal, relevant logs needed to reason about an error condition without manually navigating the Graylog UI.

Features

  • Query Graylog by absolute timestamps or relative intervals (e.g., 2026-04-09T12:34:00Z or last 15m)
  • Filter results by one or multiple Graylog stream IDs or names
  • Return structured, MCP-compatible JSON payloads suitable for model context ingestion
  • Pagination and result limiting to avoid sending huge log batches to LLMs
  • Simple HTTP endpoints for easy integration with Claude Desktop, prompt tools, or other debugging tooling
  • Configurable Graylog endpoint and API token via environment variables

Installation / Configuration

Prerequisites:

  • Access to a Graylog API endpoint and an API token with permission to search streams
  • Docker (recommended) or a local build environment if you prefer building from source

Clone the repository:

git clone https://github.com/Pranavj17/mcp-server-graylog.git
cd mcp-server-graylog

Option A — Run with Docker (recommended):

# Build image locally
docker build -t mcp-graylog .

# Run container (example)
docker run -d \
  -e GRAYLOG_URL="https://graylog.example.com/api" \
  -e GRAYLOG_API_TOKEN="your_api_token" \
  -e PORT=8080 \
  -p 8080:8080 \
  --name mcp-graylog \
  mcp-graylog

Option B — Run from source (example using a generic run command):

# If the project provides a build/run script:
./run-local.sh \
  --graylog-url https://graylog.example.com/api \
  --api-token your_api_token \
  --port 8080

Environment variables:

GRAYLOG_URL        # Graylog API base URL (required)
GRAYLOG_API_TOKEN  # API token to authenticate to Graylog (required)
PORT               # HTTP port to serve MCP API (default: 8080)
DEFAULT_LIMIT      # Optional: default max number of log messages to return

API Reference / Available Resources

Primary endpoint: GET /mcp/logs

Query parameters:

  • timestamp — absolute RFC3339 timestamp or ISO8601 (e.g., 2026-04-09T12:34:00Z). When provided with a duration, interpreted as start.
  • relative — duration relative to now (e.g., 5m, 15m, 1h). Used as interval length when timestamp is omitted or when paired to form a range.
  • streams — comma-separated stream IDs or names to filter (e.g., authentication,stream-id-123)
  • limit — maximum number of log messages to return (default controlled by DEFAULT_LIMIT)
  • direction — before | after (to fetch logs before or after the timestamp)

Example call — relative query (last 15 minutes):

curl "http://localhost:8080/mcp/logs?relative=15m&streams=auth-service,api-gateway&limit=200"

Example call — absolute window (10 minutes before timestamp):

curl "http://localhost:8080/mcp/logs?timestamp=2026-04-09T12:34:00Z&relative=10m&direction=before"

Sample JSON response:

{
  "request": { "timestamp": "2026-04-09T12:34:00Z", "relative": "10m", "streams": ["auth-service"] },
  "count": 3,
  "logs": [
    {
      "timestamp": "2026-04-09T12:29:23.123Z",
      "stream": "auth-service",
      "message": "User login failed: invalid credentials",
      "fields": { "user_id": "u-123", "ip": "10.1.1.5" }
    }
    // ...
  ]
}

Available Tools

  • HTTP API compatible with MCP consumables: use the /mcp/logs endpoint to fetch contextual logs programmatically.
  • Example Claude Desktop snippet: include the JSON result in your assistant prompt as a “context” block so the model can reason about events around a timestamp.
  • Pagination support: use offset/limit or next tokens (if provided) to page large result sets.

Use Cases

  1. Debug a production 500 error from Claude Desktop

    • Scenario: Claude Desktop reports an exception at 2026-04-09T12:34:00Z.
    • Action:
      • Request logs 5 minutes before the timestamp from relevant streams: curl “http://localhost:8080/mcp/logs?timestamp=2026-04-09T12:34:00Z&relative=5m&streams=web,api-gateway”
      • Paste the returned JSON into Claude Desktop as context to help the assistant infer root cause.

  2. Investigate intermittent authentication failures

    • Scenario: Users report login failures in the last 30 minutes.
    • Action:
      • Use a relative query: curl “http://localhost:8080/mcp/logs?relative=30m&streams=auth
Tags:search