GitHub - scottlepp/loki-mcp: An MCP ( Model Context Protocol ) Server for Grafana Loki (original) (raw)

Loki MCP Server

CI

A Go-based server implementation for the Model Context Protocol (MCP) with Grafana Loki integration.

Getting Started

Prerequisites

Building and Running

Build and run the server:

Build the server

go build -o loki-mcp-server ./cmd/server

Run the server

./loki-mcp-server

Or run directly with Go:

The server communicates using stdin/stdout following the Model Context Protocol (MCP). This makes it suitable for use with Claude Desktop and other MCP-compatible clients. It does not run as an HTTP server on a port.

Project Structure

.
├── cmd/
│   ├── server/       # MCP server implementation
│   └── client/       # Client for testing the MCP server
├── internal/
│   ├── handlers/     # Tool handlers
│   └── models/       # Data models
├── pkg/
│   └── utils/        # Utility functions and shared code
└── go.mod            # Go module definition

MCP Server

The Loki MCP Server implements the Model Context Protocol (MCP) and provides the following tools:

Loki Query Tool

The loki_query tool allows you to query Grafana Loki log data:

Environment Variables

The Loki query tool supports the following environment variables:

Testing the MCP Server

You can test the MCP server using the provided client:

Build the client

go build -o loki-mcp-client ./cmd/client

Loki query examples:

./loki-mcp-client loki_query "{job="varlogs"}" ./loki-mcp-client loki_query "{job="varlogs"}" "-1h" "now" 100

Using environment variable:

export LOKI_URL="http://localhost:3100" ./loki-mcp-client loki_query "{job="varlogs"}"

Docker Support

You can build and run the MCP server using Docker:

Build the Docker image

docker build -t loki-mcp-server .

Run the server

docker run --rm -i loki-mcp-server

Alternatively, you can use Docker Compose:

Build and run with Docker Compose

docker-compose up --build

Local Testing with Loki

The project includes a complete Docker Compose setup to test Loki queries locally:

  1. Start the Docker Compose environment:
    This will start:
    • A Loki server on port 3100
    • A Grafana instance on port 3000 (pre-configured with Loki as a data source)
    • A log generator container that sends sample logs to Loki
    • The Loki MCP server
  2. Use the provided test script to query logs:

Run with default parameters (queries last 15 minutes of logs)

./test-loki-query.sh

Query for error logs

./test-loki-query.sh '{job="varlogs"} |= "ERROR"'

Specify a custom time range and limit

./test-loki-query.sh '{job="varlogs"}' '-1h' 'now' 50 3. Insert dummy logs for testing:

Insert 10 dummy logs with default settings

./insert-loki-logs.sh

Insert 20 logs with custom job and app name

./insert-loki-logs.sh --num 20 --job "custom-job" --app "my-app"

Insert logs with custom environment and interval

./insert-loki-logs.sh --env "production" --interval 0.5

Show help message

./insert-loki-logs.sh --help 4. Access the Grafana UI at http://localhost:3000 to explore logs visually.

Server-Sent Events (SSE) Support

The server now supports two modes of communication:

  1. Standard input/output (stdin/stdout) following the Model Context Protocol (MCP)
  2. HTTP Server with Server-Sent Events (SSE) endpoint for integration with tools like n8n

The default port for the HTTP server is 8080, but can be configured using the SSE_PORT environment variable.

Server Endpoints

When running in HTTP mode, the server exposes the following endpoints:

Using Docker with SSE

When running the server with Docker, make sure to expose port 8080:

Build the Docker image

docker build -t loki-mcp-server .

Run the server with port mapping

docker run -p 8080:8080 --rm -i loki-mcp-server

n8n Integration

You can integrate the Loki MCP Server with n8n workflows:

  1. Install the MCP Client Tools node in n8n
  2. Configure the node with these parameters:
    • SSE Endpoint: http://your-server-address:8080/sse (replace with your actual server address)
    • Authentication: Choose appropriate authentication if needed
    • Tools to Include: Choose which Loki tools to expose to the AI Agent
  3. Connect the MCP Client Tool node to an AI Agent node that will use the Loki querying capabilities

Example workflow: Trigger → MCP Client Tool (Loki server) → AI Agent (Claude)

Architecture

The Loki MCP Server uses a modular architecture:

Using with Claude Desktop

You can use this MCP server with Claude Desktop to add Loki query tools. Follow these steps:

Option 1: Using the Compiled Binary

  1. Build the server:

go build -o loki-mcp-server ./cmd/server

  1. Add the configuration to your Claude Desktop configuration file using claude_desktop_config_binary.json.

Option 2: Using Go Run with a Shell Script

  1. Make the script executable:

chmod +x run-mcp-server.sh

  1. Add the configuration to your Claude Desktop configuration file using claude_desktop_config_script.json.

  1. Build the Docker image:

docker build -t loki-mcp-server .

  1. Add the configuration to your Claude Desktop configuration file using claude_desktop_config_docker.json.

Configuration Details

The Claude Desktop configuration file is located at:

You can use one of the example configurations provided in this repository:

Notes:

Or create your own configuration:

{ "mcpServers": { "lokiserver": { "command": "path/to/loki-mcp-server", "args": [], "env": { "LOKI_URL": "http://localhost:3100" }, "disabled": false, "autoApprove": ["loki_query"] } } }

Make sure to replace path/to/loki-mcp-server with the absolute path to the built binary or source code.

  1. Restart Claude Desktop.
  2. You can now use the tools in Claude:
    • Loki query examples:
      * "Query Loki for logs with the query {job="varlogs"}"
      * "Find error logs from the last hour in Loki using query {job="varlogs"} |= "ERROR""
      * "Show me the most recent 50 logs from Loki with job=varlogs"

Using with Cursor

You can also integrate the Loki MCP server with the Cursor editor. To do this, add the following configuration to your Cursor settings:

Docker configuration:

{ "mcpServers": { "loki-mcp-server": { "command": "docker", "args": ["run", "--rm", "-i", "-e", "LOKI_URL=http://host.docker.internal:3100", "loki-mcp-server:latest"] } } }

After adding this configuration, restart Cursor, and you'll be able to use the Loki query tool directly within the editor.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Running Tests

The project includes comprehensive unit tests and CI/CD workflows to ensure reliability:

Run all tests

go test ./...

Run tests with coverage

go test -coverprofile=coverage.out ./... go tool cover -func=coverage.out

Run tests with race detection

go test -race ./...

Timestamp Bug Fix (Issue #3)

This project previously had a critical bug where timestamps were displayed as year 2262 instead of correct dates. This has been fixed and regression tests are in place:

The tests specifically verify: