Loki MCP Server

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.

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"

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

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

- 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

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

# 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

The server now supports two modes of communication:
- Standard input/output (stdin/stdout) following the Model Context Protocol (MCP)
- 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 theSSE_PORTenvironment variable.

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

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

You can integrate the Loki MCP Server with n8n workflows:
-

Install the MCP Client Tools node in n8n

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

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)

The Loki MCP Server uses a modular architecture:

- Server: The main MCP server implementation incmd/server/main.go
- Client: A test client incmd/client/main.gofor interacting with the MCP server
- Handlers: Individual tool handlers ininternal/handlers/

- loki.go: Grafana Loki query functionality

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

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

- Add the configuration to your Claude Desktop configuration file usingclaude_desktop_config_binary.json.

Option 2: Using Go Run with a Shell Script

The Claude Desktop configuration file is located at:

- On macOS:~/Library/Application Support/Claude/claude_desktop_config.json
- On Windows:%APPDATA%\Claude\claude_desktop_config.json
- On Linux:~/.config/Claude/claude_desktop_config.json

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

- claude_desktop_config.json: Generic template
- claude_desktop_config_example.json: Example usinggo runwith the current path
- claude_desktop_config_binary.json: Example using the compiled binary
- claude_desktop_config_script.json: Example using a shell script (recommended forgo run)
- claude_desktop_config_docker.json: Example using Docker (most reliable)

-

When usinggo runwith Claude Desktop, you may need to set several environment variables in both the script and the configuration file:

- HOME: The user's home directory
- GOPATH: The Go workspace directory
- GOMODCACHE: The Go module cache directory
- GOCACHE: The Go build cache directory

These are required to ensure Go can find its modules and build cache when run from Claude Desktop.

Using Docker is the most reliable approach as it packages all dependencies and environment variables in a container.