grafana/mcp-grafana

Grafana MCP 服务器技术文档

1. 镜像概述

Grafana MCP（Model Context Protocol）服务器是基于Model Context Protocol的专用服务，用于模型上下文数据的处理、传输与管理。作为Grafana生态系统的重要组件，该服务器支持与Grafana Server、Grafana Loki等其他Grafana组件无缝集成，为模型相关数据的全生命周期管理提供标准化的数据传输与交互能力。

2. 核心功能与特性

2.1 协议支持

• 完整实现Model Context Protocol，支持模型上下文数据的标准化传输格式与交互逻辑。
• 兼容协议的最新稳定版本，确保与遵循该协议的客户端/服务端双向通信兼容性。

2.2 数据处理能力

• 支持模型上下文数据的接收、解析、验证与转发，确保数据完整性与格式正确性。
• 提供数据缓存机制，优化高频次模型上下文数据的访问性能。

2.3 生态集成

• 与Grafana生态深度集成，可直接对接Grafana Server实现数据可视化，或与Grafana Loki集成进行日志存储。
• 支持通过API与第三方模型管理平台（如MLflow、Kubeflow）对接，扩展数据来源与应用场景。

2.4 可配置性

• 支持通过环境变量或挂载配置文件自定义服务参数（如端口、日志级别、集成地址等）。
• 提供灵活的权限控制配置，支持基于IP或令牌的访问限制。

2.5 高可用性

• 支持单机部署与集群部署模式，集群模式下通过分布式协调机制实现负载均衡与故障转移。
• 内置健康检查接口，便于监控系统实时感知服务运行状态。

3. 使用场景与适用范围

3.1 典型使用场景

• 机器学习模型监控：跟踪模型部署后的输入/输出上下文、推理环境参数等数据，结合Grafana可视化平台实现模型性能趋势分析。
• 模型上下文数据管理：在模型训练-部署-迭代流程中，统一管理模型版本、训练环境、推理上下文等关键元数据。
• 跨系统模型数据交互：作为中间层服务，实现不同模型相关系统（如训练平台、推理引擎、监控工具）间的标准化数据传输。

3.2 适用用户

• 机器学习工程师：用于模型部署后的上下文数据跟踪与管理。
• DevOps工程师：通过集成Grafana生态实现模型相关服务的监控与运维。
• 数据平台管理员：构建标准化的模型数据传输通道，简化跨团队数据协作。

4. 使用方法与配置说明

4.1 快速部署（Docker Run）

通过docker run命令启动单机实例：

bash
docker run -d \
  --name grafana-mcp \
  -p 8080:8080 \
  -e MCP_PORT=8080 \
  -e LOG_LEVEL=info \
  -e GRAFANA_SERVER_URL=http://grafana-server:3000 \
  -e MCP_PROTOCOL_VERSION=v1 \
  docker.xuanyuan.run/grafana/mcp-server:latest

4.2 Docker Compose 部署

与Grafana Server联动部署示例：

yaml
version: '3.8'
services:
  grafana-mcp:
    image: docker.xuanyuan.run/grafana/mcp-server:latest
    container_name: grafana-mcp
    ports:
      - "8080:8080"
    environment:
      - MCP_PORT=8080                  # 服务监听端口
      - LOG_LEVEL=info                 # 日志级别（info/warn/debug/error）
      - GRAFANA_SERVER_URL=http://grafana:3000  # 对接的Grafana Server地址
      - MCP_PROTOCOL_VERSION=v1        # 协议版本
      - ALLOWED_IPS=192.168.1.0/24     # 允许访问的IP段（可选）
    depends_on:
      - grafana
    restart: unless-stopped

  grafana:
    image: docker.xuanyuan.run/grafana/grafana:latest
    container_name: grafana-server
    ports:
      - "3000:3000"
    volumes:
      - grafana-data:/var/lib/grafana
    restart: unless-stopped

volumes:
  grafana-data:

4.3 核心配置参数说明

4.4 验证部署

• 健康检查：访问 http://<部署IP>:8080/health，返回 {"status":"ok"} 表示服务正常运行。
• 日志查看：通过 docker logs grafana-mcp 检查服务启动日志，确认无错误信息。
• 协议测试：使用遵循Model Context Protocol的客户端发送测试数据，验证数据接收与转发功能。

5. 注意事项

• 生产环境建议使用集群部署模式，并配置持久化存储以保存关键配置与缓存数据。
• 若需对接外部模型管理平台，需确保网络连通性，并通过 ALLOWED_IPS 限制访问来源。
• 协议版本升级时需同步检查客户端兼容性，避免因协议不匹配导致数据传输失败。