What Loki MCP Server does
Loki MCP Server MCP server gives an MCP-compatible client read-only access to Grafana Loki. It is intended for agent-assisted log investigation: an agent can inspect available labels, construct a LogQL log query, review matching lines, measure event volume, and save results to a local file. Loki is never modified; the only write operation is the local file created by exportLogs.
The server exposes five text tools. listConnections displays configured Loki stands, operator hints, and effective limits. discoverLogs explores label names, values, and stream-label combinations. queryLogs reads bounded pages of the newest or oldest matching lines. countLogs counts matches, optionally grouped by label, time bucket, or both. exportLogs writes matching lines to a local destination using raw output or a configured rendering template.
How it works
The process communicates through MCP JSON-RPC on standard input and output. Diagnostic messages go to standard error and a local log file, leaving stdout available for protocol traffic. Each data operation requires an explicit connection name. Queries must be LogQL log queries, such as {app="backend"} |= "ERROR"; the server does not infer filters or explain the cause of an incident.
A practical workflow starts with listConnections, followed by discoverLogs to identify label names and real stream-label combinations. The agent can then use countLogs to estimate volume before retrieving lines with queryLogs. Responses are readable text rather than structured output schemas. Query pages are bounded, and default compact output shortens messages and stack traces to reduce token use. Raw query output is a preview; complete lines should be written with exportLogs.
The implementation supports Grafana Loki 2.6.1 and 3.x. Default windows, page sizes, request timeouts, and export limits are configurable per connection. Time inputs can use relative expressions, RFC3339 values, local connection time, or epoch nanoseconds.
Setup and configuration
Java 21 or newer is required. Build the JAR with the Gradle wrapper, or download the prebuilt artifact attached to a release, then launch it with java -jar. Docker images are published to GHCR; the container must run interactively so the MCP client can keep stdin open.
Connection profiles are read from ~/.loki-mcp-server/connections.json unless LOKI_MCP_CONNECTIONS_FILE points to another file. A profile includes a Loki URL and can also define a description, operator hint, timezone, service labels, authentication and tenant headers, limits, export roots, and formatting files. Configuration is validated at startup. Unknown fields, duplicate keys, missing environment variables, and invalid format files stop startup, and changes require a restart.
When using Docker, mount the directory containing connections.json at /data. Loki hostnames must be reachable from inside the container; localhost refers to the container itself. Any export directory outside the mounted data directory must also be mounted. Keep stderr separate from stdout in client configuration.
Tools and capabilities
- Discover label names, values, and matching stream-label sets.
- Run bounded newest-first or oldest-first LogQL log queries.
- Count matching lines by total, label, time bucket, or combined groups.
- Export results without overwriting an existing file.
- Apply raw output or local templates to exported lines.
- Use connection-specific limits, hints, timezones, authentication, and tenant headers.
Limitations and notes
Loki MCP Server MCP server is read-only against Loki and does not change streams or records. countLogs builds only the count_over_time expression; it does not derive filters or interpret operational causes. A Loki request times out after the configured limit, and large result sets must be narrowed or paged. Export can produce a partial file if its time limit is reached, and multiple lines sharing one nanosecond may exceed a Loki page boundary.
queryLogs has a default maximum of 1,000 lines per page. Its raw mode is limited to a preview of returned content, with stream labels and up to 4,000 code points per line; use export for complete lines. Boundary lines can repeat between pages. Discovery windows also have limits, and matching stream-label discovery should use a narrow time range when possible. URLs, credentials, tenant headers, and full log lines are excluded from tool responses and diagnostics.