Local Loki MCP server

A small, read-only MCP server for a local Grafana Loki instance. It is built with FastAPI and the official MCP Python SDK.

What it exposes

• search_logs(service, start, end, text=None) — searches a required service and optional literal text within a required RFC 3339 time range.

• list_services(start, end) — lists the available service-label values.

• loki_health() — checks whether Loki is ready.

The public tool has no limit parameter. The request also omits Loki's limit query parameter, so Loki's own configured default/maximum applies.

Related MCP server: grafana-mcp

Run it

1. Install Python 3.11 or newer, then create and activate a virtual environment.

   py -3.11 -m venv .venv
   .\.venv\Scripts\Activate.ps1
   pip install -r requirements.txt

2. Set environment variables in your shell if the defaults do not match your setup. .env.example lists the available settings. The defaults expect Loki at http://127.0.0.1:3100 and a service_name label.

3. Start the server.

   uvicorn main:app --reload

The MCP Streamable HTTP endpoint is http://127.0.0.1:8000/mcp. The server's own health endpoint is http://127.0.0.1:8000/health.

Example

Calling search_logs with:

{
  "service": "checkout",
  "text": "connection refused",
  "start": "2026-08-26T08:00:00Z",
  "end": "2026-08-26T09:00:00Z"
}

generates this LogQL query:

{service_name="checkout"} |= "connection refused"

If your labels use app instead, start the server with $env:LOKI_SERVICE_LABEL = "app".