What is Grafana Loki Mcp

grafana-loki-mcp is a FastMCP server that enables querying Loki logs through the Grafana API, facilitating efficient log management and analysis.

Use cases

Use cases for grafana-loki-mcp include monitoring application logs, debugging issues in production environments, and generating reports based on log data for analytics.

How to use

To use grafana-loki-mcp, set the environment variables GRAFANA_URL and GRAFANA_API_KEY, or provide them as command line arguments. Install the package using pip and run the server to start querying logs.

Key features

Key features include querying Loki logs via the Grafana API, retrieving Loki labels and values, formatting query results in various formats (text, JSON, markdown), and supporting both stdio and SSE transport protocols.

Where to use

grafana-loki-mcp can be used in environments that require log management and monitoring, particularly where Grafana and Loki are utilized for visualizing and analyzing log data.

Grafana-Loki MCP Server

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

1. Clone this repository
2. Install dependencies using uv:

# 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:

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

# 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:

pytest

Run with coverage:

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

Linting and Formatting

# 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

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