Grafana Loki MCP

🚀 Grafana-Loki MCP Server

A FastMCP server that allows querying Loki logs through Grafana.

🚀 Quick Start

The Grafana-Loki MCP Server is a FastMCP server enabling users to query Loki logs via Grafana. Before starting, ensure you have the necessary environment and dependencies set up.

✨ Features

• Query Loki logs.
• Retrieve labels and values from logs.
• Format query results (supports text, JSON, and Markdown).
• Support two transport protocols: stdio and SSE.

📦 Installation

Using pip

pip install grafana-loki-mcp

Development Environment

1. Clone the repository:

   git clone https://github.com/tumf/grafana-loki-mcp.git
   cd grafana-loki-mcp
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Run tests:

   python -m pytest tests/
   

💻 Usage Examples

Environment Variables

Set the following environment variables:

export GRAFANA_URL="http://localhost:3000"
export GRAFANA_API_KEY="your_api_key_here"

Command-line Arguments

Run the server:

grafana-loki-mcp --config config.yaml

Example Configuration File config.yaml

mcpServers:
  loki:
    command: uvx
    args:
      - grafana-loki-mcp
      - -u
      - http://localhost:3000
      - -k
      - your_api_key_here

Basic Usage

import asyncio
from pygql import client

async def main():
    # Initialize the client
    cli = await client("http://localhost:8090")
    
    # Query logs
    results = await cli.call(
        "query_loki",
        {
            "query": '{app="my-app"} |= "error"',
            "limit": 50,
            "max_per_line": 100,
            "start": "now-6h",
            "end": "now"
        }
    )
    
    # Format results
    formatted = await cli.call(
        "format_loki_results",
        {
            "results": results,
            "format_type": "markdown",
            "max_per_line": 100
        }
    )
    
    print(formatted)

asyncio.run(main())

Advanced Usage

Here are some available tools and their usage examples:

Query Logs (query_loki)

{
    "query": "{app=\"my-app\"} |= \"error\"",
    "limit": 50,
    "max_per_line": 100,
    "start": "now-6h",
    "end": "now"
}

Get Labels (get_loki_labels)

{
    "query": "{__name__}"
}

Format Results (format_loki_results)

{
    "results": "...",
    "format_type": "markdown",
    "max_per_line": 100
}

📚 Documentation

MCP Server Configuration

{
  "mcpServers": {
    "loki": {
      "command": "uvx",
      "args": [
        "grafana-loki-mcp",
        "-u",
        "GRAFANA_URL",
        "-k",
        "GRAFANA_API_KEY"
      ]
    }
  }
}

• GRAFANA_URL: The URL of your Grafana instance.
• GRAFANA_API_KEY: A Grafana API key with appropriate permissions.

Requirements

• Python 3.6 or higher.
• The following dependencies must be installed:
  • FastMCP
  • PyYAML

Development

Testing

Run the test suite:

pytest tests/ -v

Code Style

Use the following tools to ensure code style:

• black to format the code.
• flake8 to check for code errors.
• mypy for static type checking.

Documentation

Refer to the official documentation for detailed information.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.