grafana/loki-mcp

Purpose and Entry Points

This Go repository implements an MCP (Model Context Protocol) server that exposes a loki_query tool backed by Grafana Loki. It supports MCP over stdio for desktop/editor clients and HTTP/SSE for networked consumers.

• Server executable and protocol/transport setup: cmd/server/main.go

• Command-line MCP client for manual testing: cmd/client/main.go

• Container entrypoint packaging: Dockerfile

MCP Server and Transport Boundary

cmd/server/main.go is the application composition root. It registers the Loki tool and selects/exposes the MCP communication paths:

• stdio, intended for Claude Desktop, Cursor, and subprocess-hosted MCP clients;

• HTTP endpoints for /sse event streaming and /mcp protocol messages, with SSE_PORT controlling the listener.

The transport layer should remain protocol-focused; tool-specific request interpretation and external HTTP calls belong behind the handler boundary.

Paths: cmd/server/main.go, run-mcp-server.sh, examples/simple-sse-client.html

Loki Query Tool

The central domain operation is loki_query, implemented by the Loki handler. It accepts LogQL plus optional endpoint, time range, limit, organization, and authentication inputs; applies defaults from environment variables; then queries Loki.

The handler is the main boundary between MCP tool arguments and Loki’s HTTP API. It also carries multi-tenant context through X-Scope-OrgID and selects basic or bearer authentication from configured credentials.

Paths: internal/handlers/loki.go, internal/handlers/loki_test.go, cmd/server/main.go

Request and Response Flow

1. An MCP client sends tool discovery/invocation via stdio or the HTTP MCP/SSE transport.

2. The server dispatches loki_query to the Loki handler.

3. The handler resolves explicit parameters versus LOKI_URL, LOKI_ORG_ID, LOKI_USERNAME, LOKI_PASSWORD, and LOKI_TOKEN.

4. It makes an authenticated HTTP request to the configured Grafana Loki instance, including time window, limit, and optional tenant header.

5. Loki results are converted into the MCP tool response and returned through the originating transport.

The test client drives the same tool behavior from a shell-facing interface.

Paths: cmd/server/main.go, internal/handlers/loki.go, cmd/client/main.go

External Services and Local Observability Stack

Grafana Loki is the required external log-query service. The supplied Compose environment also provisions Grafana for inspection and Promtail/log generation for local log ingestion. Grafana is configured with Loki as a datasource.

Paths: docker-compose.yml, promtail/config.yml, grafana/provisioning/datasources/loki.yaml

Deployment and Client Integration

The service runs as a Go binary or Docker container. Containerized stdio is suitable for MCP host configuration; HTTP mode requires exposing port 8080 (or SSE_PORT). Client integration examples provide MCP host wiring rather than application-level API clients.

Paths: Dockerfile, examples/claude-desktop/claude_desktop_config_docker.json, examples/claude-desktop/claude_desktop_config_binary.json

Operational Concerns

Connection and tenant/authentication defaults are environment-driven, keeping credentials outside tool calls where possible. Authentication values are security-sensitive and must not be logged. The logger utility is shared infrastructure for server/handler diagnostics.

Paths: pkg/utils/logger.go, internal/handlers/loki.go, Dockerfile