格拉法纳MCP服务器
项目介绍
Grafana MCP 服务器
可用工具
通过MCP服务器可以使用以下工具：
- test_connection: 验证与Grafana实例的连接及配置。
- grafana_promql_query: 对Grafana的Prometheus数据源执行PromQL查询。使用PromQL表达式获取指标数据，优化时间序列响应以减少令牌大小。
- grafana_loki_query: 查询Grafana Loki的日志数据。获取指定时间段（如'5m'，'1h'，'2d'）的日志，并将相对时间转换为绝对时间戳。
- grafana_get_dashboard_config: 从数据库中检索仪表盘配置详情。查询connectors_connectormetadatamodelstore表以获取仪表盘元数据。
- grafana_query_dashboard_panels: 执行特定仪表盘面板的查询。一次最多可查询4个面板，支持模板变量，优化指标数据。
- grafana_fetch_label_values: 从Prometheus数据源获取仪表盘变量的标签值。获取特定标签（如'instance'，'job'）的可用值。支持可选的指标过滤。
- grafana_fetch_dashboard_variables: 获取Grafana仪表盘中的所有变量及其值。检索仪表盘模板变量及其当前值。
- grafana_fetch_all_dashboards: 获取Grafana中的所有仪表盘及其基本信息，如标题、UID、文件夹、标签等。
- grafana_fetch_datasources: 获取Grafana中的所有数据源及其配置详情。
- grafana_fetch_folders: 获取Grafana中的所有文件夹及其元数据和权限。
🚀 使用方法及需求
1. 获取您的Grafana API端点和服务账户令牌
- 确保您有一个正在运行的Grafana实例（自托管或云托管）。
- 从Grafana UI生成服务账户令牌：
- 创建服务账户：在您的Grafana仪表盘中，导航到管理 >> 用户与访问 >> 服务账户 >> 创建一个具有查看者权限的服务账户
- 生成服务账户密钥：在服务账户内创建一个新的服务账户令牌。
- 复制服务账户令牌（以
glsa_开头）
2. 安装及运行选项
2A. 使用uv安装并运行（推荐用于本地开发）
2A.1. 使用uv安装依赖
uv venv .venv
source .venv/bin/activate
uv sync
2A.2. 使用uv运行服务器
uv run -m src.grafana_mcp_server.mcp_server
- 您也可以使用
uv来运行其他入口脚本。 - 确保您的
config.yaml与mcp_server.py在同一目录下，或者设置所需的环境变量（参见配置部分）。
2B. 使用Docker Compose运行（推荐用于生产/容器化环境）
- 编辑
grafana-mcp-server/src/grafana_mcp_server/config.yaml，填写您的Grafana详细信息（主机、API密钥）。 - 启动服务器：
docker compose up -d- 默认情况下，服务器将在HTTP（SSE）模式下运行于8000端口。
- 您可以通过环境变量覆盖配置（参见下面）。
3. 配置
服务器按以下优先级加载配置：
- 环境变量（推荐用于Docker/CI）：
GRAFANA_HOST: Grafana实例URL（例如https://your-grafana-instance.com）GRAFANA_API_KEY: Grafana服务账户令牌（必需）GRAFANA_SSL_VERIFY:true或false（默认：true）MCP_SERVER_PORT: 运行服务器的端口（默认：8000）MCP_SERVER_DEBUG:true或false（默认：true）
- YAML文件备选方案（
config.yaml）：grafana: host: "https://your-grafana-instance.com" api_key: "your-grafana-api-key-here" ssl_verify: "true" server: port: 8000 debug: true
4. 与AI助手集成（例如Claude Desktop，Cursor）
您可以将此MCP服务器与支持MCP协议的任何工具集成。以下是主要选项：
4A. 使用Docker（带环境变量）
{
"mcpServers": {
"grafana": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"GRAFANA_HOST",
"-e",
"GRAFANA_API_KEY",
"-e",
"GRAFANA_SSL_VERIFY",
"drdroidlab/grafana-mcp-server",
"-t",
"stdio"
],
"env": {
"GRAFANA_HOST": "https://your-grafana-instance.com",
"GRAFANA_API_KEY": "your-grafana-api-key-here",
"GRAFANA_SSL_VERIFY": "true"
}
}
}
}
-t stdio参数是为了兼容Docker MCP客户端（强制使用stdio握手模式）。- 根据部署需要调整卷路径或环境变量。
4B. 连接到已运行的MCP服务器（HTTP/SSE）
如果您已经有一个运行中的MCP服务器（例如在远程主机、云VM或Kubernetes上），可以直接连接您的AI助手或工具到其HTTP端点。
{
"mcpServers": {
"grafana": {
"url": "http://your-server-host:8000/mcp"
}
}
}
- 将
your-server-host替换为您实际运行MCP服务器的主机。 - 对于本地设置，使用
localhost作为服务器主机（即http://localhost:8000/mcp）。 - 使用
http进行本地或非安全部署，使用https进行生产或安全部署。 - 确保服务器可以从客户端机器访问（检查防火墙、安全组等）。
健康检查
curl http://localhost:8000/health
服务器默认运行在8000端口。
5. 项目结构
grafana-mcp-server/
│ └── src/
│ └── grafana_mcp_server/
│ ├── __init__.py
│ ├── config.yaml # 配置文件
│ ├── mcp_server.py # 主MCP服务器实现
│ ├── stdio_server.py # MCP的STDIO服务器
│ └── processor/
│ ├── __init__.py
│ ├── grafana_processor.py # Grafana API处理器
│ └── processor.py # 基础处理器接口
├── tests/
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
└── README.md
6. 故障排除
常见问题
-
连接失败：
- 验证您的Grafana实例是否正在运行且可访问
- 检查您的API密钥是否有适当的权限
- 确保SSL验证设置与您的设置匹配
-
身份验证错误：
- 验证您的API密钥是否正确且未过期
- 检查您的Grafana实例是否需要额外的身份验证
-
查询失败：
- 确保数据源UID正确
- 验证PromQL/Loki查询语法
- 检查数据源是否可通过您的API密钥访问
调试模式
启用调试模式以获得更详细的日志：
export MCP_SERVER_DEBUG=true
7. 贡献
- 分叉仓库
- 创建功能分支（
git checkout -b feature/amazing-feature） - 提交更改（
git commit -m '添加一些很棒的功能'） - 推送到分支（
git push origin feature/amazing-feature） - 打开Pull Request
8. 许可证
该项目采用MIT许可证 - 查看LICENSE文件了解详情。
9. 支持
- 需要帮助吗？加入我们的Discord频道，并在#mcp频道留言。
- 想要一键MCP服务器？加入同一社区并告知我们。
- 对于问题和疑问，请在GitHub上打开Issue或联系维护人员。