Loki MCP server
Commit Oct 1, 2026Enables AI agents to perform read-only operations on Grafana Loki, including label discovery, LogQL queries, log counting, and file exports.
Also known as igorolv/loki-mcp-server, loki-mcp-server
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.1.0
- Last commit
- Oct 1, 2026
- License
- Apache-2.0
What is Loki MCP?
Loki enables AI agents to perform read-only operations on Grafana Loki, including label discovery, LogQL queries, log counting, and file exports.
Summary generated from the project's README
About Loki MCP server
Loki MCP Server provides a read-only interface for AI agents to interact with Grafana Loki instances. It is designed for developers and operators who need to inspect logs through an AI client using the Model Context Protocol. The server runs locally via stdio and requires a Java 21 runtime, though it can also be deployed using Docker. Users configure their environments by defining connections in a JSON file, which specifies Loki URLs, timezones, and authentication details.
The server exposes five specialized tools to facilitate log analysis. It includes discoverLogs for exploring label names and values, queryLogs for reading log lines, and countLogs for calculating log volumes over specific time buckets. For data retrieval, exportLogs allows the agent to save matching log lines to a local file using either raw text or a custom template. This setup enables an agent to navigate complex log streams and perform detailed investigations without direct manual querying.
What you can do with it
- 1Explore log labelsAn AI agent can identify available label names and specific values to understand the structure of the logs.
- 2Analyze log volumeA developer can ask an agent to count how many error logs occurred within a specific time window.
- 3Read log contentsAn agent can retrieve the most recent log entries to help debug a specific application issue.
- 4Export logs to filesA user can request the agent to save a filtered set of logs into a local text file for further analysis.
Written from the project's README. Every use case is checked against a quote from it.
How to install Loki MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Loki MCP in Claude Code
$ claude mcp add loki-mcp-server -- docker run -i --rm ghcr.io/igorolv/loki-mcp-server:0.1.0Install Loki MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"loki-mcp-server": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/igorolv/loki-mcp-server:0.1.0"
]
}
}
}Install Loki MCP in VS Code
.vscode/mcp.json
{
"servers": {
"loki-mcp-server": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/igorolv/loki-mcp-server:0.1.0"
]
}
}
}Install Loki MCP in VS Code CLI
$ code --add-mcp '{"name":"loki-mcp-server","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/igorolv/loki-mcp-server:0.1.0"]}'Install Loki MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"loki-mcp-server": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/igorolv/loki-mcp-server:0.1.0"
]
}
}
}Install Loki MCP in Codex
$ codex mcp add loki-mcp-server -- docker run -i --rm ghcr.io/igorolv/loki-mcp-server:0.1.0Install Loki MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.loki-mcp-server] command = "docker" args = ["run", "-i", "--rm", "ghcr.io/igorolv/loki-mcp-server:0.1.0"]
Install Loki MCP in Gemini CLI
$ gemini mcp add -s user loki-mcp-server docker -- run -i --rm ghcr.io/igorolv/loki-mcp-server:0.1.0Install Loki MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"loki-mcp-server": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/igorolv/loki-mcp-server:0.1.0"
]
}
}
}Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableigorolv/loki-mcp-server is public and reachablegithub.com/igorolv/loki-mcp-server ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-01github.com/igorolv/loki-mcp-server ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubLoki 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.
.\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:
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:
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:
{
"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.
Using the tools
- Call listConnections, choose a stand and use its displayed time windows, queryLogs line cap and request timeout to plan calls.
- Call discoverLogs(connection="dev") for label names, then discoverLogs(connection="dev", label="app") for values. When combinations matter, use discoverLogs(connection="dev", match="{app="backend"}") for full stream label sets or add label="namespace" for namespace values among those sets. Keep match and its window narrow; these are stream labels, not log-line counts. Widen the window on a quiet stand when appropriate.
- Use a LogQL log query with countLogs to check volume and queryLogs to read lines. For example, {app="backend"} |= "ERROR"; groupBy="time", step="1d" gives UTC-aligned 24-hour buckets, and groupBy="app,time" gives counts by app and time. A named
| regexpcapture can supply a groupBy label. Date markers distinguish buckets across midnight. - Narrow the query when a page is crowded. queryLogs defaults to the newest page; order="oldest" starts at the beginning of the window. Its footer gives an end for older lines or a start for newer ones. Boundary lines can repeat, and a timestamp containing more lines than a page needs a narrower query.
- Call exportLogs when the user asks for a file. Pass the user's destination as directory, such as
C:\tmp\logs, or omit it for the default export directory. Omitting format uses the connection's configuredexportFormattemplate, if the operator set one, and raw otherwise. format="raw" writes the lines returned by Loki, including any| line_formattransformation in the query; format="{time} {level} {service} {message}" renders locally. The response gives the path, counts and effective format, not the log contents.
queryLogs prints either end of the window in chronological order. Its default view shortens messages and stack traces to save model tokens. An optional framePattern in the connection's formatFile folds adjacent standalone frame lines in the compact view. raw=true shows every returned line with stream labels and up to 4000 code points; it is a preview. For complete lines use exportLogs. Export reads forward in pages and never overwrites an existing file. If more lines share one nanosecond than Loki will return in one page, export reports that some may be missing.
The default time window is now-1h to now. Accepted times include now-15m, RFC3339 with an offset, local time in the connection's timezone and epoch nanoseconds. queryLogs and exportLogs allow one day by default. countLogs allows one day for totals, label grouping or combined label/time grouping, and seven days for time-only buckets; discoverLogs allows seven days without match and one day with match. A Loki request has a 30-second timeout by default, and queryLogs allows at most 1000 lines per page by default. listConnections shows the effective values for each stand. Export stops after 25 seconds by default and reports a partial file with a continuation if it has written lines. After a count timeout, retry a one-day subwindow or narrower query. Limits can be set per connection; see docs/queries.md and docs/discovery.md.
MCP client configuration
Claude Code:
claude mcp add --scope user loki -e LOKI_MCP_CONNECTIONS_FILE=C:/path/connections.json -- java -jar C:/path/loki-mcp-server.jar
Codex (~/.codex/config.toml):
[mcp_servers.loki]
command = "java"
args = ["-jar", "C:/path/loki-mcp-server.jar"]
env = { LOKI_MCP_CONNECTIONS_FILE = "C:/path/connections.json" }
Other clients can launch the jar over stdio. Keep stderr separate from stdout.
Errors and diagnostics
Tool failures are text Error : with isError=true; Spring AI currently repeats the text on a second line. Missing or mistyped arguments are answered by the MCP SDK input validation. A Loki HTTP 400 LogQL parse error is returned so the model can correct its query. Other upstream response bodies, URLs, credentials, tenant and full log lines are kept out of responses and diagnostics. A 404 applies to the called endpoint, not the entire connection. Transport details are in docs/http-client.md.
The server log records connection names and auth type at startup, then one bounded line per tool call and Loki request with status, bytes and time. Log contents remain data, including text resembling instructions.
Verification
.\gradlew.bat build
.\gradlew.bat integrationTest --console=plain
python scripts/live_smoke/run_smoke.py --connection dev
build runs unit tests and a separate process stdio smoke against loopback mock Loki. integrationTest needs Docker and pinned Loki 2.6.1/3.6.0 images; it writes test data only to its containers. The live smoke uses the example profile and a configured read only stand URL. Contributor rules are in AGENTS.md; design history and open items are in docs/decisions.md. Users moving from mcp-loki can read the migration guide.
License
Apache License 2.0; see LICENSE. Third-party notices are in THIRD-PARTY-NOTICES.md.
Loki MCP questions
How do I add Loki MCP to Claude Code?
Run claude mcp add loki-mcp-server -- docker run -i --rm ghcr.io/igorolv/loki-mcp-server:0.1.0 in your terminal. Add --scope user to make it available in every project.
How do I add Loki MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Can the server write data to Loki?
No, the server is read-only for Loki; the only write operation is saving logs to a local export file.
What versions of Loki are supported?
The server supports Loki versions 2.6.1 and 3.x.
How do I configure connections to different Loki instances?
Connections are configured via a JSON file located at ~/.loki-mcp-server/connections.json or specified by the LOKI_MCP_CONNECTIONS_FILE environment variable.
What tools are available in the server?
The server provides five tools: listConnections, discoverLogs, queryLogs, countLogs, and exportLogs.