Grafana-Loki MCP Server

Grafana-Loki MCP 服务

一个 FastMCP 服务，可通过 Grafana 查询 Loki 日志。

MCP 服务设置

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

• GRAFANA_URL：Grafana 实例的 URL
• GRAFANA_API_KEY：具有相应权限的 Grafana API 密钥

功能

• 通过 Grafana API 查询 Loki 日志
• 获取 Loki 标签和标签值
• 以不同格式（文本、JSON、Markdown）格式化查询结果
• 支持 stdio 和 SSE 传输协议

要求

• Python 3.10+
• FastMCP
• Requests

安装

使用 pip

pip install grafana-loki-mcp

开发环境设置

1. 克隆此仓库
2. 使用 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]"

用法

环境变量

设置以下环境变量：

• GRAFANA_URL：Grafana 实例的 URL
• GRAFANA_API_KEY：具有相应权限的 Grafana API 密钥

命令行参数

也可以通过命令行参数提供这些值：

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

其他选项：

• --transport：要使用的传输协议（stdio 或 sse，默认值：stdio）

运行服务

# 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

开发

测试

运行测试套件：

pytest

运行并生成覆盖率报告：

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

代码检查与格式化

# Run ruff linter
ruff check .

# Run black formatter
black .

# Run type checking
mypy .

可用工具

query_loki

通过 Grafana 查询 Loki 日志。

参数：

• query：Loki 查询字符串
• start：开始时间（ISO 格式、Unix 时间戳或 Grafana 风格的相对时间，如 'now-1h'，默认值：1 小时前）
• end：结束时间（ISO 格式、Unix 时间戳或 Grafana 风格的相对时间，如 'now'，默认值：现在）
• limit：要返回的最大日志行数（默认值：100）
• direction：查询方向（'forward' 或 'backward'，默认值：'backward'）
• max_per_line：每行日志的最大字符数（0 表示不限制，默认值：100）

get_loki_labels

获取 Loki 中的所有标签名称。

get_loki_label_values

获取 Loki 中指定标签的值。

参数：

• label：标签名称

format_loki_results

以更易读的格式格式化 Loki 查询结果。

参数：

• results：来自 query_loki 的 Loki 查询结果
• format_type：输出格式（'text'、'json' 或 'markdown'，默认值：'text'）
• max_per_line：每行日志的最大字符数（0 表示不限制，默认值：0）

使用示例

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

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。