igorolv/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.
| Tool | Purpose |
|---|---|
| listConnections | Show configured stands, operator hints and effective tool limits |
| discoverLogs | List label names, values of one label, matching stream label sets, or values among those sets |
| queryLogs | Read newest or oldest bounded pages of a LogQL log query as compact text; raw=true previews returned lines and stream labels |
| countLogs | Count matching lines on Loki, optionally by label, clock aligned time bucket or both |
| exportLogs | Save matching lines to a local file, raw or rendered with a template |
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 count_over_time 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 LOKI_MCP_CONNECTIONS_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"]
}
}
}
~~~
The complete example uses environment variables for nonlocal URLs. hint gives the model stand specific selectors and field advice. serviceLabels names the labels used to display a service in compact lines. Optional formatFile names one JSON file with JSON profiles, plain-line patterns and an optional framePattern; see log-formats.json. Optional exportFormat sets the default template for exportLogs when the tool call omits format. The connection file may set exportRoots to restrict export destinations, and per connection limits. Authentication and tenant headers are configured per connection; URLs and credentials never appear in tool responses or diagnostics. The full format is in docs/connections.md.
The server loads configuration strictly at startup without probing Loki. An unknown field, duplicate key, missing environment variable or invalid format file stops startup with a safe configuration error. Changes require a restart.