Loki Go MCP Server with Grafana Integration

Overview

This project is a Go implementation of a Model Context Protocol (MCP) server that forwards and queries model context logs into Grafana Loki. It exposes MCP over stdin/stdout for direct agent integrations (for example, Claude Desktop or other MCP-compatible clients) and optionally as an HTTP server with Server-Sent Events (SSE) for real-time streaming and web integrations.

By centralizing model context and tool-output logs in Loki, teams can index, search, and visualize context history alongside application logs in Grafana. The server is lightweight, configurable via environment variables, and suitable for local development (Docker Compose) or production deployments that need multi-tenant Loki access and authentication.

Features

• MCP server implemented in Go (Go 1.16+)
• Communicates via stdin/stdout (MCP) and optional HTTP SSE endpoint
• Grafana Loki integration for querying and inserting logs
• Authentication support: basic auth and bearer token
• Configurable via environment variables and CLI
• Included test client and Docker/Docker Compose support for local testing
• Tool-based architecture: e.g., loki_query tool for LogQL queries

Installation / Configuration

Prerequisites: Go 1.16+ (or Docker)

Build and run locally:

# Build the server binary
go build -o loki-mcp-server ./cmd/server

# Run the server (stdin/stdout MCP mode)
./loki-mcp-server

Run directly with Go:

go run ./cmd/server

Docker:

# Build the Docker image
docker build -t loki-mcp-server .

# Run the container (interactive, reads stdin)
docker run --rm -i loki-mcp-server

Docker Compose (includes Loki + Grafana for local testing):

# Build and bring up services
docker-compose up --build -d

Environment variables (defaults noted):

Security note: Avoid checking credentials into source control. Prefer bearer tokens and secrets management; redact logs that may contain credentials.

Available Tools

The server exposes a set of tools via MCP. The main provided tool:

• loki_query
  • Purpose: Run LogQL queries against Loki and return matched log entries.
  • Required parameter: query (LogQL string)
  • Optional parameters: url, start, end, limit, org

Example usage with the provided test client:

# Build the client
go build -o loki-mcp-client ./cmd/client

# Simple query
./loki-mcp-client loki_query '{job="varlogs"}'

# Query with time range and limit
./loki-mcp-client loki_query '{job="varlogs"}' '-1h' 'now' 100

When parameters are omitted, the tool falls back to LOKI_* environment variables.

Endpoints (HTTP mode)

When started with HTTP/SSE enabled, default endpoints are:

• SSE stream: http://localhost:8080/sse
• MCP over http: http://localhost:8080/mcp

SSE is useful for web UIs, integrations like n8n, or any client that prefers a streaming HTTP interface.

Use Cases

• Real-time agent debugging: Stream model context and tool outputs into Loki, then view in Grafana to investigate agent decisions and environment state.
  • Example: Run the MCP server locally with Docker Compose, have your agent connect over stdin/stdout, then open Grafana at http://localhost:3000 to explore logs and dashboards.
• Multi-tenant log queries: Use LOKI_ORG_ID to scope queries for tenant-specific logs in a multi-tenant Loki deployment.
  • Example: set LOKI_ORG_ID=tenant-123 and invoke loki_query to retrieve only that tenant’s entries.
• Web integrations: Expose SSE to push model context events to a browser-based dashboard or an automation platform like n8n for live monitoring.
  • Example: Connect to /sse and render received events in a live timeline UI.

Testing and Local Development

• Use the included Docker Compose to spin up Loki, Grafana, sample log generator, and the MCP server.
• Scripts provided in the repo:
  • test-loki-query.sh — run sample queries
  • insert-loki-logs.sh — insert synthetic logs for demo/QA

Example local test:

docker-compose up -d
./test-loki-query.sh '{job="varlogs"}' '-15m' 'now' 50

Project Layout (quick)

• cmd/server — MCP server
• cmd/client — test client
• internal/handlers — tool implementations
• internal/models — request/response models
• pkg/utils — shared helpers

For source, issues, and contributions: https://github.com/scottlepp/loki-mcp