loki

The Loki MCP Server is a Go-based implementation of the Model Context Protocol (MCP) that integrates Grafana Loki for log querying. It exposes a Loki query tool through the MCP interface, allowing clients to send MCP messages to request logs and receive results via the server’s streaming protocol. The server communicates over standard input/output (stdin/stdout) following MCP, and it also offers an HTTP SSE endpoint for real-time event streaming and integration with tools like n8n. To use the server, build or run the binary and then issue MCP commands to the server to perform Loki queries using the loki_query tool. The included Loki query tool supports environment-driven defaults for Loki connection details and can be customized per-request with parameters like query, start, end, limit, and org to handle multi-tenant setups.

Prerequisites:

• Go 1.16 or higher
• A Go toolchain installed and accessible in your PATH

Install and build from source:

1. Clone the repository git clone https://github.com/scottlepp/loki-mcp cd loki-mcp

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

3. Run the server locally ./loki-mcp-server

4. (Optional) Run directly with Go go run ./cmd/server

If you prefer Docker:

1. Build the Docker image (from the repository root) docker build -t loki-mcp-server .

2. Run the server with Docker docker run --rm -i loki-mcp-server

Notes:

• The server communicates via MCP over stdin/stdout by default. Use the provided client binary (from ./cmd/client) for testing, or integrate via the HTTP SSE endpoint if needed.
• For environment-based Loki configuration, you can set LOKI_URL, LOKI_ORG_ID, LOKI_USERNAME, LOKI_PASSWORD, and LOKI_TOKEN as defaults when invoking the Loki query tool.

Tips and caveats:

• Environment variables are supported to provide default Loki connection/auth details for the Loki query tool (LOKI_URL, LOKI_ORG_ID, LOKI_USERNAME, LOKI_PASSWORD, LOKI_TOKEN). Be careful not to log sensitive credentials.
• If you deploy via Docker, expose port 8080 when using the SSE HTTP mode and configure the SSE_PORT environment variable as needed.
• The Loki query tool supports optional parameters (start, end, limit) and an org parameter for multi-tenant environments. If not specified, sensible defaults are used (e.g., last 1 hour, 100 results).
• Use the provided Docker Compose setup for local Loki testing, which includes Loki, Grafana, a log generator, and the Loki MCP server for end-to-end testing.
• When integrating with Claude Desktop or n8n, ensure the correct endpoints are used for MCP/ SSE and expose the necessary tools (Loki query tool) to the agent.
• If you observe connection or authentication issues, verify that the Loki service is reachable at the default LOKI_URL or the URL provided in your request, and confirm network accessibility between services.