Skip to content
Back to search

loki-mcp

An MCP ( Model Context Protocol ) Server for Grafana Loki

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/scottlepp--loki-mcp/badge.svg)](/listings/scottlepp--loki-mcp)

HTML

<a href="/listings/scottlepp--loki-mcp"><img src="/api/listings/scottlepp--loki-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 401 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Loki MCP Server
  2. [![CI](https://github.com/scottlepp/loki-mcp/workflows/CI/badge.svg)](https://github.com/scottlepp/loki-mcp/actions/workflows/ci.yml)
  3. A Go-based server implementation for the Model Context Protocol (MCP) with Grafana Loki integration.
  4. ## Getting Started
  5. ### Prerequisites
  6. - Go 1.16 or higher
  7. ### Building and Running
  8. Build and run the server:
  9. ```bash
  10. # Build the server
  11. go build -o loki-mcp-server ./cmd/server
  12. # Run the server
  13. ./loki-mcp-server
  14. ```
  15. Or run directly with Go:
  16. ```bash
  17. go run ./cmd/server
  18. ```
  19. 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.
  20. ## Project Structure
  21. ```
  22. .
  23. ├── cmd/
  24. │ ├── server/ # MCP server implementation
  25. │ └── client/ # Client for testing the MCP server
  26. ├── internal/
  27. │ ├── handlers/ # Tool handlers
  28. │ └── models/ # Data models
  29. ├── pkg/
  30. │ └── utils/ # Utility functions and shared code
  31. └── go.mod # Go module definition
  32. ```
  33. ## MCP Server
  34. The Loki MCP Server implements the Model Context Protocol (MCP) and provides the following tools:
  35. ### Loki Query Tool
  36. The `loki_query` tool allows you to query Grafana Loki log data:
  37. - Required parameters:
  38. - `query`: LogQL query string
  39. - Optional parameters:
  40. - `url`: The Loki server URL (default: from LOKI_URL environment variable or http://localhost:3100)
  41. - `start`: Start time for the query (default: 1h ago)
  42. - `end`: End time for the query (default: now)
  43. - `limit`: Maximum number of entries to return (default: 100)
  44. - `org`: Organization ID for the query (sent as X-Scope-OrgID header)
  45. #### Environment Variables
  46. The Loki query tool supports the following environment variables:
  47. - `LOKI_URL`: Default Loki server URL to use if not specified in the request
  48. - `LOKI_ORG_ID`: Default organization ID to use if not specified in the request
  49. - `LOKI_USERNAME`: Default username for basic authentication if not specified in the request
  50. - `LOKI_PASSWORD`: Default password for basic authentication if not specified in the request
  51. - `LOKI_TOKEN`: Default bearer token for authentication if not specified in the request
  52. **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.
  53. ### Testing the MCP Server
  54. You can test the MCP server using the provided client:
  55. ```bash
  56. # Build the client
  57. go build -o loki-mcp-client ./cmd/client
  58. # Loki query examples:
  59. ./loki-mcp-client loki_query "{job=\"varlogs\"}"
  60. ./loki-mcp-client loki_query "{job=\"varlogs\"}" "-1h" "now" 100
  61. # Using environment variables:
  62. export LOKI_URL="http://localhost:3100"
  63. ./loki-mcp-client loki_query "{job=\"varlogs\"}"
  64. # Using environment variables for both URL and org:
  65. export LOKI_URL="http://localhost:3100"
  66. export LOKI_ORG_ID="tenant-123"
  67. ./loki-mcp-client loki_query "{job=\"varlogs\"}"
  68. # Using environment variables for authentication:
  69. export LOKI_URL="http://localhost:3100"
  70. export LOKI_USERNAME="admin"
  71. export LOKI_PASSWORD="password"
  72. ./loki-mcp-client loki_query "{job=\"varlogs\"}"
  73. # Using environment variables with bearer token:
  74. export LOKI_URL="http://localhost:3100"
  75. export LOKI_TOKEN="your-bearer-token"
  76. ./loki-mcp-client loki_query "{job=\"varlogs\"}"
  77. # Using all environment variables together:
  78. export LOKI_URL="http://localhost:3100"
  79. export LOKI_ORG_ID="tenant-123"
  80. export LOKI_USERNAME="admin"
  81. export LOKI_PASSWORD="password"
  82. ./loki-mcp-client loki_query "{job=\"varlogs\"}"
  83. # Using org parameter for multi-tenant setups:
  84. ./loki-mcp-client loki_query "{job=\"varlogs\"}" "" "" "" "" "" "tenant-123"
  85. ```
  86. ## Docker Support
  87. You can build and run the MCP server using Docker:
  88. ```bash
  89. # Build the Docker image
  90. docker build -t loki-mcp-server .
  91. # Run the server
  92. docker run --rm -i loki-mcp-server
  93. ```
  94. Alternatively, you can use Docker Compose:
  95. ```bash
  96. # Build and run with Docker Compose
  97. docker-compose up --build
  98. ```
  99. ### Local Testing with Loki
  100. The project includes a complete Docker Compose setup to test Loki queries locally:
  101. 1. Start the Docker Compose environment:
  102. ```bash
  103. docker-compose up -d
  104. ```
  105. This will start:
  106. - A Loki server on port 3100
  107. - A Grafana instance on port 3000 (pre-configured with Loki as a data source)
  108. - A log generator container that sends sample logs to Loki
  109. - The Loki MCP server
  110. 2. Use the provided test script to query logs:
  111. ```bash
  112. # Run with default parameters (queries last 15 minutes of logs)
  113. ./test-loki-query.sh
  114. # Query for error logs
  115. ./test-loki-query.sh '{job="varlogs"} |= "ERROR"'
  116. # Specify a custom time range and limit
  117. ./test-loki-query.sh '{job="varlogs"}' '-1h' 'now' 50
  118. ```
  119. 3. Insert dummy logs for testing:
  120. ```bash
  121. # Insert 10 dummy logs with default settings
  122. ./insert-loki-logs.sh
  123. # Insert 20 logs with custom job and app name
  124. ./insert-loki-logs.sh --num 20 --job "custom-job" --app "my-app"
  125. # Insert logs with custom environment and interval
  126. ./insert-loki-logs.sh --env "production" --interval 0.5
  127. # Show help message
  128. ./insert-loki-logs.sh --help
  129. ```
  130. 4. Access the Grafana UI at http://localhost:3000 to explore logs visually.
  131. ## Server-Sent Events (SSE) Support
  132. The server now supports two modes of communication:
  133. 1. Standard input/output (stdin/stdout) following the Model Context Protocol (MCP)
  134. 2. HTTP Server with Server-Sent Events (SSE) endpoint for integration with tools like n8n
  135. The default port for the HTTP server is 8080, but can be configured using the `SSE_PORT` environment variable.
  136. ### Server Endpoints
  137. When running in HTTP mode, the server exposes the following endpoints:
  138. - SSE Endpoint: `http://localhost:8080/sse` - For real-time event streaming
  139. - MCP Endpoint: `http://localhost:8080/mcp` - For MCP protocol messaging
  140. ### Using Docker with SSE
  141. When running the server with Docker, make sure to expose port 8080:
  142. ```bash
  143. # Build the Docker image
  144. docker build -t loki-mcp-server .
  145. # Run the server with port mapping
  146. docker run -p 8080:8080 --rm -i loki-mcp-server
  147. ```
  148. ### n8n Integration
  149. You can integrate the Loki MCP Server with n8n workflows:
  150. 1. Install the MCP Client Tools node in n8n
  151. 2. Configure the node with these parameters:
  152. - **SSE Endpoint**: `http://your-server-address:8080/sse` (replace with your actual server address)
  153. - **Authentication**: Choose appropriate authentication if needed
  154. - **Tools to Include**: Choose which Loki tools to expose to the AI Agent
  155. 3. Connect the MCP Client Tool node to an AI Agent node that will use the Loki querying capabilities
  156. Example workflow:
  157. Trigger → MCP Client Tool (Loki server) → AI Agent (Claude)
  158. ## Architecture
  159. The Loki MCP Server uses a modular architecture:
  160. - **Server**: The main MCP server implementation in `cmd/server/main.go`
  161. - **Client**: A test client in `cmd/client/main.go` for interacting with the MCP server
  162. - **Handlers**: Individual tool handlers in `internal/handlers/`
  163. - `loki.go`: Grafana Loki query functionality
  164. ## Using with Claude Desktop
  165. You can use this MCP server with Claude Desktop to add Loki query tools. Follow these steps:
  166. ### Option 1: Using the Compiled Binary
  167. 1. Build the server:
  168. ```bash
  169. go build -o loki-mcp-server ./cmd/server
  170. ```
  171. 2. Add the configuration to your Claude Desktop configuration file using `claude_desktop_config_binary.json`.
  172. ### Option 2: Using Go Run with a Shell Script
  173. 1. Make the script executable:
  174. ```bash
  175. chmod +x run-mcp-server.sh
  176. ```
  177. 2. Add the configuration to your Claude Desktop configuration file using `claude_desktop_config_script.json`.
  178. ### Option 3: Using Docker (Recommended)
  179. 1. Build the Docker image:
  180. ```bash
  181. docker build -t loki-mcp-server .
  182. ```
  183. 2. Add the configuration to your Claude Desktop configuration file using `claude_desktop_config_docker.json`.
  184. ### Configuration Details
  185. The Claude Desktop configuration file is located at:
  186. - On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  187. - On Windows: `%APPDATA%\Claude\claude_desktop_config.json`
  188. - On Linux: `~/.config/Claude/claude_desktop_config.json`
  189. You can use one of the example configurations provided in this repository:
  190. - `claude_desktop_config.json`: Generic template
  191. - `claude_desktop_config_example.json`: Example using `go run` with the current path
  192. - `claude_desktop_config_binary.json`: Example using the compiled binary
  193. - `claude_desktop_config_script.json`: Example using a shell script (recommended for `go run`)
  194. - `claude_desktop_config_docker.json`: Example using Docker (most reliable)
  195. **Notes**:
  196. - When using `go run` with Claude Desktop, you may need to set several environment variables in both the script and the configuration file:
  197. - `HOME`: The user's home directory
  198. - `GOPATH`: The Go workspace directory
  199. - `GOMODCACHE`: The Go module cache directory
  200. - `GOCACHE`: The Go build cache directory
  201. These are required to ensure Go can find its modules and build cache when run from Claude Desktop.
  202. - Using Docker is the most reliable approach as it packages all dependencies and environment variables in a container.
  203. Or create your own configuration:
  204. ```json
  205. {
  206. "mcpServers": {
  207. "lokiserver": {
  208. "command": "path/to/loki-mcp-server",
  209. "args": [],
  210. "env": {
  211. "LOKI_URL": "http://localhost:3100",
  212. "LOKI_ORG_ID": "your-default-org-id",
  213. "LOKI_USERNAME": "your-username",
  214. "LOKI_PASSWORD": "your-password",
  215. "LOKI_TOKEN": "your-bearer-token"
  216. },
  217. "disabled": false,
  218. "autoApprove": ["loki_query"]
  219. }
  220. }
  221. }
  222. ```
  223. Make sure to replace `path/to/loki-mcp-server` with the absolute path to the built binary or source code.
  224. 4. Restart Claude Desktop.
  225. 5. You can now use the tools in Claude:
  226. - Loki query examples:
  227. - "Query Loki for logs with the query {job=\"varlogs\"}"
  228. - "Find error logs from the last hour in Loki using query {job=\"varlogs\"} |= \"ERROR\""
  229. - "Show me the most recent 50 logs from Loki with job=varlogs"
  230. - "Query Loki for logs with org 'tenant-123' using query {job=\"varlogs\"}"
  231. ### Using Organization ID in Natural Language Prompts
  232. When using this MCP server with Claude Desktop or other AI assistants, users can naturally mention the organization ID in their prompts in several ways:
  233. #### Direct Organization Reference
  234. - **"Query Loki for logs from organization 'tenant-123' with the query {job=\"varlogs\"}"**
  235. - **"Search Loki logs for org 'production-env' using {job=\"web\"}"**
  236. - **"Get logs from organization ID 'client-abc' matching {service=\"api\"}"**
  237. #### Contextual Organization Mentions
  238. - **"Check the error logs for our production tenant (org: prod-001) using query {level=\"error\"}"**
  239. - **"Find all logs from customer organization 'customer-xyz' for the last hour"**
  240. - **"Query Loki with org tenant-456 to find logs matching {job=\"backend\"}"**
  241. #### Multi-tenant Scenarios
  242. - **"Switch to organization 'dev-team' and query {job=\"logs\"} for debugging"**
  243. - **"Use org 'staging-env' to search for warning logs in the last 2 hours"**
  244. - **"Search logs in tenant 'qa-environment' for any error messages"**
  245. #### Combined with Other Parameters
  246. - **"Query Loki for organization 'prod-cluster' from 2 hours ago to now with limit 50"**
  247. - **"Get the last 100 logs from org 'microservice-team' for query {app=\"payment\"}"**
  248. When you mention any of these natural language prompts, the AI assistant will automatically map terms like "organization", "org", "tenant", or "organization ID" to the `org` parameter in the Loki query tool, which gets sent as the `X-Scope-OrgID` header to your Loki server for proper multi-tenant filtering.
  249. The key is to naturally mention any specific parameters in your request - the AI will understand how to map them to the appropriate Loki query tool parameters. When parameters are not explicitly mentioned, the system will automatically use defaults from environment variables:
  250. - `LOKI_URL` for the Loki server URL
  251. - `LOKI_ORG_ID` for the organization ID
  252. - `LOKI_USERNAME` and `LOKI_PASSWORD` for basic authentication
  253. - `LOKI_TOKEN` for bearer token authentication
  254. This makes it very convenient to set up default connection parameters once and then use natural language queries without having to specify authentication details every time.
  255. ## Using with Cursor
  256. You can also integrate the Loki MCP server with the Cursor editor. To do this, add the following configuration to your Cursor settings:
  257. Docker configuration:
  258. ```json
  259. {
  260. "mcpServers": {
  261. "loki-mcp-server": {
  262. "command": "docker",
  263. "args": ["run", "--rm", "-i",
  264. "-e", "LOKI_URL=http://host.docker.internal:3100",
  265. "-e", "LOKI_ORG_ID=your-default-org-id",
  266. "-e", "LOKI_USERNAME=your-username",
  267. "-e", "LOKI_PASSWORD=your-password",
  268. "-e", "LOKI_TOKEN=your-bearer-token",
  269. "loki-mcp-server:latest"]
  270. }
  271. }
  272. }
  273. ```
  274. After adding this configuration, restart Cursor, and you'll be able to use the Loki query tool directly within the editor.
  275. ## License
  276. This project is licensed under the MIT License - see the LICENSE file for details.
  277. ## Running Tests
  278. The project includes comprehensive unit tests and CI/CD workflows to ensure reliability:
  279. ```bash
  280. # Run all tests
  281. go test ./...
  282. # Run tests with coverage
  283. go test -coverprofile=coverage.out ./...
  284. go tool cover -func=coverage.out
  285. # Run tests with race detection
  286. go test -race ./...
  287. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.