grafana-loki-mcp

# Grafana-Loki MCP Server [](https://github.com/tumf/grafana-loki-mcp/actions/workflows/test.yml) [](https://badge.fury.io/py/grafana-loki-mcp) [](https://codecov.io/gh/tumf/grafana-loki-mcp) [](https://opensource.org/licenses/MIT) A [FastMCP](https://github.com/jlowin/fastmcp) server that allows querying Loki logs from Grafana. ## MCP Server Settings ```json { "mcpServers": { "loki": { "command": "uvx", "args": [ "grafana-loki-mcp", "-u", "GRAFANA_URL", "-k", "GRAFANA_API_KEY" ] } } } ``` - `GRAFANA_URL`: URL of your Grafana instance - `GRAFANA_API_KEY`: Grafana API key with appropriate permissions ## Features - Query Loki logs through Grafana API - Get Loki labels and label values - Format query results in different formats (text, JSON, markdown) - Support for both stdio and SSE transport protocols ## Requirements - Python 3.10+ - FastMCP - Requests ## Installation ### Using pip ```bash pip install grafana-loki-mcp ``` ### Development Setup 1. Clone this repository 2. Install dependencies using uv: ```bash # Install uv pip install uv # Create and activate virtual environment uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate # Install dependencies uv pip install -e ".[dev]" ``` ## Usage ### Environment Variables Set the following environment variables: - `GRAFANA_URL`: URL of your Grafana instance - `GRAFANA_API_KEY`: Grafana API key with appropriate permissions ### Command Line Arguments You can also provide these values as command line arguments: ```bash grafana-loki-mcp -u https://your-grafana-instance.com -k your-api-key ``` Additional options: - `--transport`: Transport protocol to use (`stdio` or `sse`, default: `stdio`) ### Running the Server ```bash # Using environment variables export GRAFANA_URL=https://your-grafana-instance.com export GRAFANA_API_KEY=your-api-key grafana-loki-mcp # Using command line arguments grafana-loki-mcp -u https://your-grafana-instance.com -k your-api-key # Using SSE transport grafana-loki-mcp --transport sse ``` ## Development ### Testing Run the test suite: ```bash pytest ``` Run with coverage: ```bash pytest --cov=. --cov-report=term ``` ### Linting and Formatting ```bash # Run ruff linter ruff check . # Run black formatter black . # Run type checking mypy . ``` ## Available Tools ### query_loki Query Loki logs through Grafana. Parameters: - `query`: Loki query string - `start`: Start time (ISO format, Unix timestamp, or Grafana-style relative time like 'now-1h', default: 1 hour ago) - `end`: End time (ISO format, Unix timestamp, or Grafana-style relative time like 'now', default: now) - `limit`: Maximum number of log lines to return (default: 100) - `direction`: Query direction ('forward' or 'backward', default: 'backward') - `max_per_line`: Maximum characters per log line (0 for unlimited, default: 100) ### get_loki_labels Get all label names from Loki. ### get_loki_label_values Get values for a specific label from Loki. Parameters: - `label`: Label name ### format_loki_results Format Loki query results in a more readable format. Parameters: - `results`: Loki query results from query_loki - `format_type`: Output format ('text', 'json', or 'markdown', default: 'text') - `max_per_line`: Maximum characters per log line (0 for unlimited, default: 0) ## Example Usage ```python # Example client code from mcp.client import Client async with Client() as client: # Query Loki logs with max_per_line limit results = await client.call_tool( "query_loki", { "query": '{app="my-app"} |= "error"', "limit": 50, "max_per_line": 100, # Limit log lines to 100 characters "start": "now-6h", # Grafana-style relative time: 6 hours ago "end": "now" # Current time } ) # Format the results formatted = await client.call_tool( "format_loki_results", { "results": results, "format_type": "markdown", "max_per_line": 100 # Can also limit at formatting time } ) print(formatted) ``` ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.