Grafana-Loki MCP Server

1# Grafana-Loki MCP Server
2 
3[![Test](https://github.com/tumf/grafana-loki-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/tumf/grafana-loki-mcp/actions/workflows/test.yml)
4[![PyPI version](https://badge.fury.io/py/grafana-loki-mcp.svg)](https://badge.fury.io/py/grafana-loki-mcp)
5[![codecov](https://codecov.io/gh/tumf/grafana-loki-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/tumf/grafana-loki-mcp)
6[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7 
8A [FastMCP](https://github.com/jlowin/fastmcp) server that allows querying Loki logs from Grafana.
9 
10## MCP Server Settings
11 
12```json
13{
14  "mcpServers": {
15    "loki": {
16      "command": "uvx",
17      "args": [
18        "grafana-loki-mcp",
19        "-u",
20        "GRAFANA_URL",
21        "-k",
22        "GRAFANA_API_KEY"
23      ]
24    }
25  }
26}
27```
28 
29- `GRAFANA_URL`: URL of your Grafana instance
30- `GRAFANA_API_KEY`: Grafana API key with appropriate permissions
31 
32## Features
33 
34- Query Loki logs through Grafana API
35- Get Loki labels and label values
36- Format query results in different formats (text, JSON, markdown)
37- Support for both stdio and SSE transport protocols
38 
39## Requirements
40 
41- Python 3.10+
42- FastMCP
43- Requests
44 
45## Installation
46 
47### Using pip
48 
49```bash
50pip install grafana-loki-mcp
51```
52 
53### Development Setup
54 
551. Clone this repository
562. Install dependencies using uv:
57 
58```bash
59# Install uv
60pip install uv
61 
62# Create and activate virtual environment
63uv venv
64source .venv/bin/activate  # On Windows: .venv\Scripts\activate
65 
66# Install dependencies
67uv pip install -e ".[dev]"
68```
69 
70## Usage
71 
72### Environment Variables
73 
74Set the following environment variables:
75 
76- `GRAFANA_URL`: URL of your Grafana instance
77- `GRAFANA_API_KEY`: Grafana API key with appropriate permissions
78 
79### Command Line Arguments
80 
81You can also provide these values as command line arguments:
82 
83```bash
84grafana-loki-mcp -u https://your-grafana-instance.com -k your-api-key
85```
86 
87Additional options:
88- `--transport`: Transport protocol to use (`stdio` or `sse`, default: `stdio`)
89 
90### Running the Server
91 
92```bash
93# Using environment variables
94export GRAFANA_URL=https://your-grafana-instance.com
95export GRAFANA_API_KEY=your-api-key
96grafana-loki-mcp
97 
98# Using command line arguments
99grafana-loki-mcp -u https://your-grafana-instance.com -k your-api-key
100 
101# Using SSE transport
102grafana-loki-mcp --transport sse
103```
104 
105## Development
106 
107### Testing
108 
109Run the test suite:
110 
111```bash
112pytest
113```
114 
115Run with coverage:
116 
117```bash
118pytest --cov=. --cov-report=term
119```
120 
121### Linting and Formatting
122 
123```bash
124# Run ruff linter
125ruff check .
126 
127# Run black formatter
128black .
129 
130# Run type checking
131mypy .
132```
133 
134## Available Tools
135 
136### query_loki
137 
138Query Loki logs through Grafana.
139 
140Parameters:
141- `query`: Loki query string
142- `start`: Start time (ISO format, Unix timestamp, or Grafana-style relative time like 'now-1h', default: 1 hour ago)
143- `end`: End time (ISO format, Unix timestamp, or Grafana-style relative time like 'now', default: now)
144- `limit`: Maximum number of log lines to return (default: 100)
145- `direction`: Query direction ('forward' or 'backward', default: 'backward')
146- `max_per_line`: Maximum characters per log line (0 for unlimited, default: 100)
147 
148### get_loki_labels
149 
150Get all label names from Loki.
151 
152### get_loki_label_values
153 
154Get values for a specific label from Loki.
155 
156Parameters:
157- `label`: Label name
158 
159### format_loki_results
160 
161Format Loki query results in a more readable format.
162 
163Parameters:
164- `results`: Loki query results from query_loki
165- `format_type`: Output format ('text', 'json', or 'markdown', default: 'text')
166- `max_per_line`: Maximum characters per log line (0 for unlimited, default: 0)
167 
168## Example Usage
169 
170```python
171# Example client code
172from mcp.client import Client
173 
174async with Client() as client:
175    # Query Loki logs with max_per_line limit
176    results = await client.call_tool(
177        "query_loki",
178        {
179            "query": '{app="my-app"} |= "error"',
180            "limit": 50,
181            "max_per_line": 100,  # Limit log lines to 100 characters
182            "start": "now-6h",    # Grafana-style relative time: 6 hours ago
183            "end": "now"          # Current time
184        }
185    )
186 
187    # Format the results
188    formatted = await client.call_tool(
189        "format_loki_results",
190        {
191            "results": results,
192            "format_type": "markdown",
193            "max_per_line": 100  # Can also limit at formatting time
194        }
195    )
196 
197    print(formatted)
198```
199 
200## License
201 
202This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
203