grafana-loki-mcp - MCP Servers Directory

A FastMCP server that allows querying Loki logs from Grafana.

MCP Server Settings

{
  "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

pip install grafana-loki-mcp

Development Setup

Clone this repository
Install dependencies using uv:

pip install uv

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

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:

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

export GRAFANA_URL=https://your-grafana-instance.com
export GRAFANA_API_KEY=your-api-key
grafana-loki-mcp

grafana-loki-mcp -u https://your-grafana-instance.com -k your-api-key

grafana-loki-mcp --transport sse

Development

Testing

Run the test suite:

pytest

Run with coverage:

pytest --cov=. --cov-report=term

Linting and Formatting

ruff check .

black .

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

from mcp.client import Client

async with Client() as client:
    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
        }
    )

    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 file for details.