Overwatch

You will run an MCP server named Overwatch that lets you query Graylog, Prometheus, and InfluxDB 2.x from Claude Desktop. This guide shows practical steps to install, configure, and use the MCP server to retrieve logs and metrics across your monitoring stack.

How to use

Connect your Claude Desktop client to the MCP server to issue queries against Graylog, Prometheus, and InfluxDB. Use the available tools to search logs, list fields, and run PromQL or Flux queries. You can also filter results, set time ranges, and apply bucket allowlists for InfluxDB queries. Ensure your MCP is running and that environment variables point to your Graylog, Prometheus, and InfluxDB instances.

How to install

Prerequisites: you need Docker for container-based setup or Python for local runtime. Choose one of the following installation paths.

Two quick setup options

Option 1: Docker one-line setup.

curl -fsSL https://raw.githubusercontent.com/malindarathnayake/Overwatch-mcp/main/compose/setup.sh | bash
docker compose up -d

Option 2: Docker manual setup using the provided compose files.

mkdir -p Overwatch_MCP && cd Overwatch_MCP
curl -fsSLO https://raw.githubusercontent.com/malindarathnayake/Overwatch-mcp/main/compose/docker-compose.yml
curl -fsSLO https://raw.githubusercontent.com/malindarathnayake/Overwatch-mcp/main/compose/.env.example
curl -fsSLO https://raw.githubusercontent.com/malindarathnayake/Overwatch-mcp/main/compose/config.example.yaml

cp .env.example .env
cp config.example.yaml config.yaml
# Edit .env with your credentials
# Edit config.yaml if needed (adjust allowed_buckets, limits, etc.)

docker compose up -d

Option 3: Local Python installation to run the MCP server directly from source.

pip install -e .
cp .env.example .env
cp config/config.example.yaml config/config.yaml
# Edit both files with your values
python -m overwatch_mcp

Claude Desktop config for running the MCP server

You can configure Claude Desktop to start the MCP server either via Docker or as a local Python process.

Docker configuration for Claude Desktop

{
  "mcpServers": {
    "overwatch": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/path/to/config:/app/config:ro",
        "--env-file", "/path/to/.env",
        "ghcr.io/malindarathnayake/Overwatch-mcp:latest"
      ]
    }
  }
}

Local Python configuration for Claude Desktop

{
  "mcpServers": {
    "overwatch": {
      "command": "python",
      "args": ["-m", "overwatch_mcp"],
      "env": {
        "GRAYLOG_URL": "https://graylog.internal:9000/api",
        "GRAYLOG_TOKEN": "your-token",
        "PROMETHEUS_URL": "http://prometheus.internal:9090",
        "INFLUXDB_URL": "https://influxdb.internal:8086",
        "INFLUXDB_TOKEN": "your-token",
        "INFLUXDB_ORG": "your-org"
      }
    }
  }
}

Windows PowerShell setup

Use a one-shot script to configure Claude Desktop on Windows. This sets up the MCP server to run via Python with a configured YAML config and environment variables.

# Stop Claude if running
Get-Process -Name "Claude*" -ErrorAction SilentlyContinue | Stop-Process -Force

$config = @'
{
  "mcpServers": {
    "overwatch": {
      "command": "C:/Users/<USERNAME>/AppData/Local/Microsoft/WindowsApps/python3.13.exe",
      "args": ["-m", "overwatch_mcp", "--config", "C:/path/to/Overwatch-mcp/compose/config.yaml"],
      "env": {
        "GRAYLOG_URL": "https://your-graylog-url",
        "GRAYLOG_TOKEN": "<YOUR_GRAYLOG_TOKEN>",
        "PROMETHEUS_URL": "http://your-prometheus-url:9090",
        "INFLUXDB_URL": "https://your-influxdb-url",
        "INFLUXDB_TOKEN": "<YOUR_INFLUXDB_TOKEN>",
        "INFLUXDB_ORG": "<YOUR_INFLUXDB_ORG>",
        "LOG_LEVEL": "debug",
        "LOG_FILE": "C:/path/to/Overwatch-mcp/overwatch.log"
      }
    }
  }
}
'@
[System.IO.File]::WriteAllText("$env:APPDATA\Claude\claude_desktop_config.json", $config)

# Install from source (run from repo root)
cd C:\path\to\Overwatch-mcp
pip install -e .

Configuration

The MCP server uses environment variable substitutions at runtime. The following YAML shows how the server is connected to your data sources and how you tune its behavior.

server:
  log_level: "info"

datasources:
  graylog:
    enabled: true
    url: "${GRAYLOG_URL}"
    token: "${GRAYLOG_TOKEN}"
    timeout_seconds: 30
    max_time_range_hours: 24
    max_results: 1000
    production_environments:
      - "prod"
      - "production"
    known_applications_file: "${GRAYLOG_KNOWN_APPS_FILE:-}"

  prometheus:
    enabled: true
    url: "${PROMETHEUS_URL}"
    timeout_seconds: 30
    max_range_hours: 168

  influxdb:
    enabled: true
    url: "${INFLUXDB_URL}"
    token: "${INFLUXDB_TOKEN}"
    org: "${INFLUXDB_ORG}"
    timeout_seconds: 60
    allowed_buckets:
      - "telegraf"
      - "app_metrics"

cache:
  enabled: true
  default_ttl_seconds: 60

Error handling and troubleshooting

If a datasource is disabled or unavailable, the MCP server will continue operating with the remaining sources. Ensure data source URLs and tokens are correct and that network access is permitted. Validate that time ranges and query syntax conform to the supported formats.

Development

If you want to contribute, install with development dependencies, run tests, and check test coverage.

# Install with dev deps
pip install -e ".[dev]"

# Tests
pytest tests/ -v

# Coverage
pytest tests/ -v --cov=overwatch_mcp

Project structure

The MCP server source is organized to separate the core server, configuration, and data source clients. You will find the main entry point, server logic, configuration loader, cache, HTTP clients for data sources, tool implementations, and models.

Usage guide

To learn practical usage patterns, explore workflows for finding errors, inspecting logs with filters and time ranges, querying metrics, and following investigation patterns across your monitoring stack.

Troubleshooting

Server won’t start: Verify that the configuration file exists and required environment variables are set. Datasource unavailable: Check the datasource URL and permissions. Query errors: Ensure syntax correctness for Lucene, PromQL, or Flux, respect time range limits, and confirm the requested InfluxDB bucket is allowed.

License

MIT license.

Notes

This MCP server is designed to centralize access to log and metric data sources from Claude Desktop, enabling streamlined investigations and monitoring across Graylog, Prometheus, and InfluxDB.

Available tools

graylog_search

Search logs using Lucene syntax with a specified time window and field selection.

graylog_fields

List available log fields matching a pattern with a limit.

prometheus_query

Execute an instant PromQL query at a specific time.

prometheus_query_range

Execute a range PromQL query over a time interval with a defined step.

prometheus_metrics

List metrics matching a pattern with a limit.

influxdb_query

Run a Flux query against a specific InfluxDB bucket.