# 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.

## Run it

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

   ```powershell
   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.

   ```powershell
   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:

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

generates this LogQL query:

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

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