Loki MCP Server
Give MCP clients a direct way to query Grafana Loki with LogQL.
- Source repo
- grafana-cold-storage/loki-mcp
- Stars
- ★ 176
- Last updated
- 1y ago
- Primary language
- Go
- FA score
- 41/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformClaude.ai
- Cost
- Free, no paid service needed
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- An operations engineer uses Claude Desktop to turn a request for recent service errors into a LogQL query against Loki.
- Not a fit if
- Teams needing a ready-made log backend; Loki itself is not included
- Teams needing label discovery, alerting, or rule administration
- Users wanting zero-config setup; you must deploy Loki and configure ports and credentials
- Source review
- 41/100 · Major gaps 2 safety controls not found
What does this agent do, and when should you use it?
Loki MCP Server is a Go implementation of the Model Context Protocol for Grafana Loki. Its loki_query tool accepts LogQL, a time range, a result limit, and an optional organization ID, then returns results obtained from Loki. The server can run as a standard input/output MCP process or expose HTTP endpoints at /sse and /mcp. The repository also includes a test client, tool handlers, data models, and a Docker Compose environment containing Loki, Grafana, sample-log generation, and the MCP server. It fits teams that want Claude Desktop, Cursor, n8n, or another MCP-compatible client to reach a self-hosted Loki deployment, but it is not a general-purpose log backend and does not supply Loki itself.
An MCP client calls loki_query with the required query LogQL string and may also provide url, start, end, limit, and org. The handler queries the selected Grafana Loki server, sends org as the X-Scope-OrgID header, and returns the resulting log entries to the client. When values are omitted, it can read connection, tenant, and authentication settings from LOKI_URL, LOKI_ORG_ID, LOKI_USERNAME, LOKI_PASSWORD, and LOKI_TOKEN; documented defaults are http://localhost:3100, one hour ago through now, and 100 entries. The process supports stdin/stdout MCP as well as HTTP mode with /sse and /mcp on port 8080 by default. The cmd/client program exercises the tool directly, while the Docker Compose setup can generate sample logs and make them available for inspection in Grafana.
- An operations engineer uses Claude Desktop to turn a request for recent service errors into a LogQL query against Loki.
- A platform team operating multi-tenant Loki selects a tenant with the
orgparameter and sends the correspondingX-Scope-OrgIDheader. - An n8n maintainer connects an MCP Client Tools node to
/sseso an AI Agent can retrieve logs during a workflow. - A developer starts Loki, Grafana, a log generator, and the MCP server with Docker Compose to test queries and client configuration locally.
- A Cursor user runs the server in Docker and queries application logs from the editor while investigating a defect.
How do you install or deploy this agent?
Install Go 1.16 or newer and ensure a Grafana Loki server is reachable. Build and start the server with:
go build -o loki-mcp-server ./cmd/server
./loki-mcp-serverAlternatively, run it directly:
go run ./cmd/serverFor a container deployment:
docker build -t loki-mcp-server .
docker run --rm -i loki-mcp-serverExpose the default HTTP/SSE port when needed:
docker run -p 8080:8080 --rm -i loki-mcp-serverSet LOKI_URL for the Loki endpoint. Multi-tenant deployments may set LOKI_ORG_ID; authentication uses either LOKI_USERNAME plus LOKI_PASSWORD, or LOKI_TOKEN. The HTTP port can be changed with SSE_PORT.
How do you use this agent?
Configure Loki and make a first test query:
export LOKI_URL="http://localhost:3100"
go build -o loki-mcp-client ./cmd/client
./loki-mcp-client loki_query "{job=\"varlogs\"}"To supply a time range and result limit, run:
./loki-mcp-client loki_query "{job=\"varlogs\"}" "-1h" "now" 100For the complete local test environment, run docker-compose up -d, followed by ./test-loki-query.sh '{job="varlogs"} |= "ERROR"'. For Claude Desktop, register the built binary as an MCP server, provide the required LOKI_URL and authentication environment variables, and restart the client before invoking loki_query. HTTP integrations can connect to http://your-server-address:8080/sse; MCP protocol messages use http://your-server-address:8080/mcp.
What are this agent's strengths and limitations?
- Supports both stdin/stdout and HTTP/SSE delivery, covering desktop MCP clients and network-based workflows such as n8n.
loki_queryexposes time bounds, result limits, and an organization ID, with explicitX-Scope-OrgIDsupport for multi-tenant Loki.- Supports both basic authentication and bearer tokens, with connection and credential defaults configurable through environment variables.
- Includes a test client, query and log-insertion scripts, plus a Docker Compose environment with Loki, Grafana, and generated sample logs.
- The documented product scope centers on one
loki_querytool; there is no evidenced label discovery, rule administration, alert management, or production log-ingestion interface. - Adoption requires an existing or separately deployed Grafana Loki service, plus network and port configuration for HTTP/SSE use.
- Usernames, passwords, and tokens may be supplied through environment variables, so operators must prevent credentials from leaking into logs or configuration.
- Repository metadata lists the license as unknown while the README claims MIT; adopters should verify the actual
LICENSEfile. - Using
go runfrom Claude Desktop may require additionalHOME,GOPATH,GOMODCACHE, andGOCACHEconfiguration, which is why the documentation characterizes Docker as the more reliable route.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Loki MCP Server This agent | 41 · Major gaps | MCP serverFree | ★ 176 | 1y ago | Go | Claude.ai |
| Agency Orchestrator: One Sentence to Orchestrate an AI Expert Team | 71 · Some gaps | CLIFree + model costs | ★ 2.5k | 5d ago | TypeScript | Codex · Claude Code · OpenAI API · Claude API |
| OpenSandbox Runtime | 74 · Some gaps | Library / SDKFree | ★ 17k | today | Python | Codex · Claude Code |
| T3MP3ST Security Harness | 69 · Some gaps | CLIFree + model costs | ★ 7k | 2mo ago | TypeScript | Codex · Claude Code · OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
The source shows Loki query tools connecting through a URL, organization ID, and authentication environment variables. README and server code describe stdio, SSE, and HTTP data paths, so data flow is reasonably clear. Deductions: no least-privilege controls or user confirmation are shown, and a configuration example includes autoApprove; credential guidance is limited to a warning, with no further protections shown; the HTTP server binds on all interfaces and implementation of authentication is not documented; no rollback mechanism is shown. Module paths and CI provide limited provenance clues, but publisher identity and maintenance responsibility remain unverified.
README, go.mod, and CI describe the Go version, dependency, and intended build and test workflow, while the server registers three Loki tools. Deductions: README lists Go 1.16, but go.mod and CI point to Go 1.24.4; CI's integration test is commented out; handler implementation is absent from the sample, preventing review of behavior and error handling. The client has some explicit error messages, but end-to-end server and query failure messages cannot be assessed from the sample.
Documentation targets MCP clients, Claude Desktop, Cursor, and n8n, and provides query parameters, organization ID, environment variables, and several run modes. The described tool intent is focused on Loki queries. Deductions: only tool registration is visible, so capability boundaries cannot be confirmed; port documentation conflicts with code (README says SSE_PORT while code uses PORT); cross-environment authentication and HTTP security requirements are only lightly documented.
README includes project structure, build and run steps, configuration, examples, Docker, and license sections; directory descriptions are clear and tool and environment names are fairly stable. Deductions: the LICENSE file is not in the sample, so only the MIT claim is visible; no changelog or maintainer is shown; known limitations are sparse, and documentation conflicts on the Go version and port configuration.
The MCP tools bring LogQL queries into compatible clients and expose time range, limit, and organization parameters; examples cover common queries and multi-tenant use. Deductions: beyond the query parameters, the README gives little detail on output format or scale limits; handler implementation is absent, so output usability and benefit over manual querying cannot be assessed; deployment and credential configuration add operational effort.
README tool names, parameters, and environment variables partly correspond to tool registration and client request structure; dependency versions and CI steps are stated explicitly. Deductions: handler source, test source, and LICENSE are absent from the sample, while CI integration tests are commented out; the claims of comprehensive tests and coverage are not independently supported by the supplied material; the materials do not consistently distinguish implemented facts from expected client behavior.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Before deployment, reconcile the Go version and port settings in the README and code, and verify the actual HTTP listen address and access controls.
- Handler and test sources are absent from the sample; do not treat README claims about comprehensive tests or coverage as verified by this review.
- A configuration example includes autoApprove, and the service supports Loki requests with credentials; configure credentials and tool approval policy carefully for the actual client and network.
Maintain this project? Add the FARS badge to your README
[](https://followagents.com/en/agents/loki-mcp)<a href="https://followagents.com/en/agents/loki-mcp"><img src="https://followagents.com/badge/loki-mcp.svg" alt="FARS review"></a>Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
What's Changed * support multiple results formats by @scottlepp in https://github.com/grafana/loki-mcp/pull/11 Full Changelog: https://github.com/grafana/loki-mcp/compare/v0.5.0...v0.6.0View on GitHub ↗ -
Release notes excerpt
What's Changed * add labels tools by @scottlepp in https://github.com/grafana/loki-mcp/pull/10 Full Changelog: https://github.com/grafana/loki-mcp/compare/v0.4.0...v0.5.0View on GitHub ↗ -
Release notes excerpt
What's Changed * add streamable by @scottlepp in https://github.com/grafana/loki-mcp/pull/9 Full Changelog: https://github.com/grafana/loki-mcp/compare/v0.3.0...v0.4.0View on GitHub ↗
FAQ
Does it host Loki or collect logs?
Does it support multi-tenant Loki?
org per request or set LOKI_ORG_ID; the value is sent to Loki in the X-Scope-OrgID header.How can it authenticate to Loki?
LOKI_USERNAME and LOKI_PASSWORD, or bearer authentication through LOKI_TOKEN. The documentation recommends token-based authentication when possible and warns against exposing credentials.Is Docker mandatory?
What should I check when a query fails?
LOKI_URL is reachable, the LogQL expression is valid, the selected time range contains data, and the tenant and authentication values match the target Loki configuration.Thanks — we use this to improve the page.