Loki MCP Server

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

Getting Started

Prerequisites

• Go 1.16 or higher

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:

go run ./cmd/server

The server communicates using stdin/stdout and SSE following the Model Context Protocol (MCP). This makes it suitable for use with Claude Desktop and other MCP-compatible clients.

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:

• Required parameters:

  • query: LogQL query string

• Optional parameters:

  • url: The Loki server URL (default: from LOKI_URL environment variable or http://localhost:3100)
  • start: Start time for the query (default: 1h ago)
  • end: End time for the query (default: now)
  • limit: Maximum number of entries to return (default: 100)
  • org: Organization ID for the query (sent as X-Scope-OrgID header)

Environment Variables

The Loki query tool supports the following environment variables:

• LOKI_URL: Default Loki server URL to use if not specified in the request
• LOKI_ORG_ID: Default organization ID to use if not specified in the request
• LOKI_USERNAME: Default username for basic authentication if not specified in the request
• LOKI_PASSWORD: Default password for basic authentication if not specified in the request
• LOKI_TOKEN: Default bearer token for authentication if not specified in the request

Security Note: When using authentication environment variables, be careful not to expose sensitive credentials in logs or configuration files. Consider using token-based authentication over username/password when possible.

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 variables:
export LOKI_URL="http://localhost:3100"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

# Using environment variables for both URL and org:
export LOKI_URL="http://localhost:3100"
export LOKI_ORG_ID="tenant-123"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

# Using environment variables for authentication:
export LOKI_URL="http://localhost:3100"
export LOKI_USERNAME="admin"
export LOKI_PASSWORD="password"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

# Using environment variables with bearer token:
export LOKI_URL="http://localhost:3100"
export LOKI_TOKEN="your-bearer-token"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

# Using all environment variables together:
export LOKI_URL="http://localhost:3100"
export LOKI_ORG_ID="tenant-123"
export LOKI_USERNAME="admin"
export LOKI_PASSWORD="password"
./loki-mcp-client loki_query "{job=\"varlogs\"}"

# Using org parameter for multi-tenant setups:
./loki-mcp-client loki_query "{job=\"varlogs\"}" "" "" "" "" "" "tenant-123"

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 Com

... View full README on GitHub