Loki MCP Server

Loki MCP Server

A local stdio MCP server for reading Grafana Loki with an agent. It exposes five text tools and supports Loki 2.6.1 and 3.x. Loki itself is read only; the only write is a local exportLogs file.

Every data tool requires an explicit connection. queryLogs, countLogs and exportLogs require a LogQL log query, such as {app="backend"} |= "ERROR". Use discoverLogs to find label names, values and real combinations in stream label sets. The server builds only the countovertime expression for countLogs; it does not infer filters or interpret causes. Tool responses are readable text without an output schema.

Build and run

JDK 21 or newer is required; the project uses a Java 21 toolchain and the Gradle wrapper.

~~~powershell .\gradlew.bat bootJar java -jar build/libs/loki-mcp-server.jar ~~~

On Linux/macOS use ./gradlew. The process waits for MCP JSON-RPC on stdin. stdout is reserved for JSON-RPC; diagnostics go to stderr and ~/.loki-mcp-server/logs/loki-mcp-server.log.

A prebuilt loki-mcp-server.jar is attached to every release, so building is optional.

For Claude Code, registering the jar is one command:

~~~bash claude mcp add --scope user loki -- java -jar /path/to/loki-mcp-server.jar ~~~

Docker

The image is published to GHCR with every release. Mount the directory holding connections.json at /data; the server also writes its logs and default exports there:

~~~bash docker run -i --rm -v ~/.loki-mcp-server:/data ghcr.io/igorolv/loki-mcp-server:latest ~~~

The same command is what an MCP client should launch; -i keeps stdin open for the stdio transport. Loki URLs in connections.json must be reachable from inside the container: use the Loki host name rather than localhost, or add --network host on Linux. An exportLogs directory outside /data is a path inside the container, so mount it as well. To build the image locally: docker build -t loki-mcp-server .

Connections

The server reads ~/.loki-mcp-server/connections.json, or the path in LOKIMCPCONNECTIONS_FILE. A minimal file:

~~~json { "connections": { "dev": { "description": "Development", "hint": "Start with {app=\"backend\"}; inspect app values with discoverLogs.", "url": "http://localhost:3100", "timezone": "Europe/Moscow", "serviceLabels": ["app", "container"] } } } ~~~

Shortened. The full README is on GitHub.