grafana/loki-mcp

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:
Or run directly with Go:
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
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:
Docker Support
You can build and run the MCP server using Docker:
Alternatively, you can use Docker Compose:
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:
3. Insert dummy logs for testing:
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:
- SSE Endpoint: http://localhost:8080/sse - For real-time event streaming
- MCP Endpoint: http://localhost:8080/mcp - For MCP protocol messaging
Using Docker with SSE
When running the server with Docker, make sure to expose port 8080:
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)