Loki MCP Server

A Model Context Protocol (MCP) server for Grafana Loki that provides AI agents with access to log data.

Overview

The Loki MCP Server allows AI agents to query and analyze logs stored in Grafana Loki, providing additional context to Large Language Models (LLMs). It implements the Model Context Protocol to expose tools and resources for interacting with Loki.

Features

Tools

- query_logs: Execute LogQL queries and retrieve matching log entries
- get_log_labels: Retrieve all label names available in the logs
- get_label_values: Get all values for a specific label
- get_log_volume: Analyze log volume over time

Resources

- Log streams by label selector: Access log streams filtered by a LogQL label selector
- URI template: loki://logs/{selector}
- Example: loki://logs/app="frontend",env="prod"

- Recent error logs: Access recent error logs across all services
- URI: loki://errors/recent

- Service logs: Access logs for a specific service
- URI template: loki://service/{service_name}/logs
- Example: loki://service/frontend/logs

Installation

Prerequisites

- Go 1.18 or later
- Access to a Grafana Loki instance

Building from Source

1. Clone the repository:

   git clone https://github.com/scottlepper/loki-mcp-server.git

   cd loki-mcp-server

   

2. Build the server:

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

   

Configuration

The server can be configured using command-line flags or environment variables:

| Flag | Environment Variable | Description | Default |
|------|---------------------|-------------|---------|
| --loki-url | LOKI_URL | URL of the Loki instance | http://localhost:3100/ |
| --username | LOKI_USERNAME | Username for basic auth | |
| --password | LOKI_PASSWORD | Password for basic auth | |
| --api-key | LOKI_API_KEY | API key for authentication | |
| --tenant-id | LOKI_TENANT_ID | Tenant ID for multi-tenant setups | |
| --query-timeout | QUERY_TIMEOUT | Timeout for queries | 30s |

Usage

Starting the Server

./loki-mcp-server --loki-url=http://loki.example.com:3100/

Or with environment variables:

LOKI_URL=http://loki.example.com:3100/ ./loki-mcp-server

Using Docker Compose

A Docker Compose setup is provided for easy testing with a complete Loki stack:

1. Start the environment:

   docker-compose up -d

   

This will start:
- Grafana Loki for log storage
- Promtail for log collection
- Grafana for log visualization
- The Loki MCP Server

2. Access Grafana at http://localhost:3000 to view logs

3. Configure an MCP-compatible AI agent to connect to the Loki MCP Server

4. For convenience, you can use the provided test script:

   ./examples/docker-test.sh

   

Using with MCP-compatible AI Agents

To use the Loki MCP Server with an MCP-compatible AI agent, you need to configure the agent to connect to the server. The specific configuration depends on the agent you're using.

Standard Configuration

For example, with Claude Desktop, you would add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "loki": {
      "command": "/path/to/loki-mcp-server",
      "args": ["--loki-url=http://loki.example.com:3100/"],
      "env": {
        "LOKI_API_KEY": "your-api-key"
      }
    }
  }
}

Docker Compose Configuration

If you're using the Docker Compose setup, you can configure Claude Desktop to connect to the containerized MCP server:

{
  "mcpServers": {
    "loki": {
      "command": "docker",
      "args": ["exec", "-i", "loki-mcp-server-loki-mcp-server-1", "/app/loki-mcp-server"],
      "env": {},
      "disabled": false,
      "autoApprove": []
    }
  }
}

Example configurations are provided in the examples directory:
- examples/claude_desktop_config.json: Standard configuration
- examples/claude_desktop_docker_config.json: Docker Compose configuration

Examples

Querying Logs

Use the query_logs tool to find error logs in the frontend service from the last hour.

Getting Label Values

Use the get_label_values tool to list all possible values for the "app" label.

Accessing Service Logs

Access the logs for the authentication service using the loki://service/auth/logs resource.

Development

Project Structure

- cmd/loki-mcp-server/: Main application entry point
- pkg/mcp/: MCP protocol implementation
- pkg/loki/: Loki client and tools implementation

Running Tests

go test ./...

License

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