使用说明

@leval/mcp-grafana（这个名称在中文中没有直接的翻译，因为它是一个特定的项目或模块名称，但可以解释为“leval项目的MCP-Grafana组件”或“leval中的MCP与Grafana集成模块”，具体翻译需根据上下文确定）

为Grafana完成Model Context Protocol（MCP）服务器的TypeScript/JavaScript实现，使AI助手能够与Grafana仪表板、数据源、警报、事件等进行交互。

🚀 功能

43种综合工具通过MCP实现完整的Grafana功能
支持多个MCP客户端与Claude Desktop、Claude Code、Cursor、Zed、Codex兼容
类型安全的实现使用TypeScript构建，确保可靠性
轻松安装可通过 npm/npx 使用 - 无需编译
生产就绪全面的错误处理和日志记录
全面支持身份验证服务帐户、API密钥、基本身份验证、mTLS

📦 安装

选项1：全局安装

npm install -g @leval/mcp-grafana

选项2：使用npx运行（无需安装）

npx @leval/mcp-grafana

选项3：本地开发

git clone https://github.com/levalhq/mcp-grafana.git
cd mcp-grafana
npm install
npm run build

🔧 配置

环境变量

创建一个 .env 在项目根目录下的文件：

# Required
GRAFANA_URL=https://your-grafana-instance.com

# Authentication (use one)
GRAFANA_SERVICE_ACCOUNT_TOKEN=glsa_xxxxxxxxxxxx  # Recommended
# OR
GRAFANA_USERNAME=username                        # Basic auth
GRAFANA_PASSWORD=password

# Optional
DEBUG=true                                       # Enable debug logging
TLS_CERT_FILE=/path/to/cert.pem                # mTLS certificate
TLS_KEY_FILE=/path/to/key.pem                  # mTLS key
TLS_CA_FILE=/path/to/ca.pem                    # Custom CA certificate
TLS_SKIP_VERIFY=true                            # Skip TLS verification

🤖 MCP 客户端配置

Claude 桌面版

配置文件位置：

macOS:（可翻译为）苹果操作系统 ~/Library/Application Support/Claude/claude_desktop_config.json
Windows： %APPDATA%\Claude\claude_desktop_config.json
Linux： ~/.config/Claude/claude_desktop_config.json

配置:

{
  "mcpServers": {
    "grafana": {
      "command": "npx",
      "args": ["@leval/mcp-grafana"],
      "env": {
        "GRAFANA_URL": "https://your-grafana.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxxxxxxxxxxx"
      }
    }
  }
}

使用方法：

保存配置文件
重启Claude桌面版
在界面上查找MCP图标（🔌）
询问Claude：“我的Grafana中有哪些可用的仪表板？”

Claude 扩展（VS Code 扩展）

{
  "claude.mcpServers": {
    "grafana": {
      "command": "npx",
      "args": ["@leval/mcp-grafana"],
      "env": {
        "GRAFANA_URL": "https://your-grafana.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxxxxxxxxxxx"
      }
    }
  }
}

或者在VS Code设置中进行全局配置：

打开命令面板 (Cmd/Ctrl + Shift + P)
搜索“首选项：打开用户设置（JSON）”
添加 claude.mcpServers 配置

使用方法：

在VS Code中打开Claude面板
MCP服务器将自动启动
询问：“给我看看我们Prometheus指标中的错误率。”

光标

配置添加到 .cursor/settings.json 在你的项目根目录中：

{
  "ai.mcpServers": {
    "grafana": {
      "command": "npx",
      "args": ["@leval/mcp-grafana"],
      "env": {
        "GRAFANA_URL": "https://your-grafana.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxxxxxxxxxxx"
      }
    }
  }
}

或者全局配置：

打开光标设置（Cmd/Ctrl + ,)
前往“功能”→“人工智能”→“MCP服务器”
添加Grafana服务器配置

使用：

按压 Cmd/Ctrl + K 打开AI聊天
当连接时，MCP指示灯将会亮起
尝试：“分析过去一小时内的Loki日志中的错误”

泽德（Zed）

配置添加到 ~/.config/zed/settings.json:

{
  "assistant": {
    "version": "2",
    "mcp_servers": {
      "grafana": {
        "command": "npx",
        "args": ["@leval/mcp-grafana"],
        "env": {
          "GRAFANA_URL": "https://your-grafana.com",
          "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxxxxxxxxxxx"
        }
      }
    }
  }
}

使用方法:

打开助手面板（Cmd/Ctrl + ?)
MCP服务器自动启动
询问：“列出所有数据源及其类型”

Codex（GitHub Copilot 工作区）

配置添加到 .github/codex/mcp-config.json：

{
  "servers": {
    "grafana": {
      "command": "npx",
      "args": ["@leval/mcp-grafana"],
      "env": {
        "GRAFANA_URL": "https://your-grafana.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxxxxxxxxxxx"
      }
    }
  }
}

使用方法:

打开Codex工作区
MCP服务器自动连接
在提示中使用：“基于我们当前的指标创建一个仪表板”

Continue.dev（可译为“继续开发平台”或根据具体语境灵活翻译，但“Continue.dev”本身作为专有名词，直译为“继续点开发”并不准确，需结合上下文理解其实际含义）

配置添加到 ~/.continue/config.json：

{
  "models": [...],
  "mcpServers": {
    "grafana": {
      "command": "npx",
      "args": ["@leval/mcp-grafana"],
      "env": {
        "GRAFANA_URL": "https://your-grafana.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxxxxxxxxxxx"
      }
    }
  }
}

使用方法：

在你的集成开发环境（IDE）中打开“继续”面板
状态栏中显示的MCP连接状态
问：“当前有哪些警报正在触发？”

风帆冲浪

配置添加到 .windsurf/mcp-servers.json:

{
  "grafana": {
    "command": "npx",
    "args": ["@leval/mcp-grafana"],
    "env": {
      "GRAFANA_URL": "https://your-grafana.com",
      "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxxxxxxxxxxx"
    }
  }
}

使用方法：

Windsurf 自动检测并连接到 MCP 服务器
在Grafana上下文中使用Cascade AI

📚 可用工具（共43个）

仪表盘管理（5种工具）

工具	描述	示例用法
`search_dashboards`	搜索仪表板	“查找名称中包含'cpu'的仪表板”
`get_dashboard_by_uid`	获取完整的仪表板 JSON	“向我展示 UID 为 abc123 的仪表板”
`get_dashboard_summary`	获取仪表板元数据	“总结监控仪表板”
`get_dashboard_property`	提取特定属性	“从仪表板xyz中获取所有面板标题”
`update_dashboard`	创建或更新仪表板	“添加一个新面板以跟踪内存使用情况”

数据来源（3种工具）

工具	描述	示例用法
`list_datasources`	列出所有数据源	“已配置哪些数据源？”
`get_datasource_by_uid`	通过UID获取数据源	"显示数据源uid-123的详细信息"
`get_datasource_by_name`	通过名称获取数据源	"获取Prometheus数据源配置"

Prometheus（5种工具）

工具	描述	示例用法
`query_prometheus`	执行PromQL查询	“显示过去一小时的CPU使用率”
`list_prometheus_metric_names`	列出可用指标	“有哪些可用的指标？”
`list_prometheus_label_names`	列表标签名称	“显示所有Prometheus标签”
`list_prometheus_label_values`	获取标签值	“'env' 标签存在哪些值？”
`list_prometheus_metric_metadata`	获取指标元数据	“描述 node_cpu_seconds 指标”

Loki 日志（5种工具）

工具	描述	示例用法
`query_loki_logs` 执行LogQL查询	“显示来自API服务的错误日志”
`query_loki_stats`	获取日志流统计信息	“过去一天内有多少条日志条目？”
`list_loki_label_names`	列出日志标签名称	“我们的日志中有哪些标签？”
`list_loki_label_values`	获取日志标签值	“在日志中显示所有命名空间”
`find_error_pattern_logs`	查找错误模式	“分析生产中的错误模式”

事件管理（4种工具）

工具	描述	示例用法
`list_incidents`	列出事件	“显示所有活跃事件”
`get_incident`	获取事件详情	“事件 INC-123 的详情”
`create_incident` 创建新事件	“为API中断创建一个严重事件”
`add_activity_to_incident`	在事件中添加备注	“为事件INC-123添加更新”

附加类别

警报；提醒 （3种工具）：告警规则，联系点
OnCall 翻译成中文是“随时待命”或“应召服务” （5种工具）：时间表、班次、值班用户
过筛 (4种工具)：调查、慢请求分析
Pyroscope（可译为“热像仪”或根据具体上下文可能译为“热成像系统”等，但此处保留原英文以体现其技术专有名词性） (4种工具)：性能剖析数据，性能分析
管理员 （2种工具）：用户和团队管理
导航 (1 工具)：生成 Grafana 深度链接
断言 (1 工具)：实体断言

🔒 安全

创建服务帐户令牌（推荐）

在Grafana用户界面中：
- 进入“管理”→“服务帐户”
- 点击“添加服务帐户”
- 给它命名（例如，“mcp-server”）
- 点击“创建”
- 点击“添加服务账户令牌”
- 生成令牌并复制它
所需权限：
- dashboards:read - 查看仪表板
- datasources:read - 查看数据源
- alert.rules:read - 查看警报规则
- logs:read - 查询Loki
- metrics:read - 查询 Prometheus
- incidents:write - 处理事件（如需）

最佳实践

使用服务帐户令牌而不是API密钥
将令牌存储在环境变量中，而非代码中
尽可能使用只读权限
为生产环境启用TLS/mTLS
定期更换令牌

🧪 测试

快速测试

# Test connection
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-grafana.com/api/org

# Test with the MCP server
npx @leval/mcp-grafana --debug

运行测试套件

# Clone the repository
git clone https://github.com/levalhq/mcp-grafana.git
cd mcp-grafana

# Install dependencies
npm install

# Run tests
npm test

# Test with your Grafana instance
node test/test-connection.js
node test/test-api.js

📊 性能

启动时间< 1秒
工具注册所有43个工具均在100毫秒内完成
查询响应典型值为200-500毫秒
内存使用量~50MB 基线
连接池重用HTTP连接

🐛 故障排除

MCP服务器无法启动

# Check if running correctly
npx @leval/mcp-grafana --debug

# Should output:
# Starting MCP Grafana server with stdio transport...
# MCP server started with stdio transport

连接问题

# Test your credentials
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-grafana.com/api/org

# Check response - should return org details

客户端未检测到服务器

验证配置文件位置
检查JSON语法是否有效
重启客户端应用程序
在用户界面中查找MCP指示器
检查客户端日志中的错误

常见的错误信息

错误	解决方案
“身份验证失败”	请检查您的服务帐户令牌
“未找到数据源”	验证数据源权限
“未找到工具”	确保所有工具均已启用
“连接超时”	检查网络和Grafana URL
“权限被拒绝”	为服务帐户添加所需权限

📈 高级配置

禁用特定工具类别

npx @leval/mcp-grafana \
  --disable-incident \
  --disable-oncall \
  --disable-sift

自定义TLS配置

export TLS_CERT_FILE=/path/to/cert.pem
export TLS_KEY_FILE=/path/to/key.pem
export TLS_CA_FILE=/path/to/ca.pem
npx @leval/mcp-grafana

调试模式

npx @leval/mcp-grafana --debug
# Or
export DEBUG=true
npx @leval/mcp-grafana

🤝 贡献

欢迎贡献！请随时提交拉取请求。

# Fork and clone
git clone https://github.com/levalhq/mcp-grafana.git
cd mcp-grafana

# Install dependencies
npm install

# Make changes and test
npm test

# Build
npm run build

# Submit PR

功能状态

所有原始Go语言实现的功能均已迁移：

✅ 带有stdio传输的核心MCP服务器
✅ 仪表板操作（搜索、检索、更新、创建）
✅ 数据源管理
✅ Prometheus 查询和元数据
✅ Loki日志查询与标签探索
✅ 事件管理和时间线
✅ 告警管理及联系点
✅ 值班安排和轮班表
✅ 进行筛选、调查和分析
✅ Pyroscope性能分析
✅ 认证方法（API密钥、服务帐户、基本认证、mTLS）
✅ TLS配置和自定义CA支持

📄 许可证

Apache-2.0 - 查看许可证文件中有详细信息

📦 NPM 包

这个包已发布在npm上，名为 @leval/mcp-grafana

# Install globally
npm install -g @leval/mcp-grafana

# Or use directly with npx
npx @leval/mcp-grafana

# View package info
npm info @leval/mcp-grafana

🆘 支持

NPM 包: npmjs.com 上的包：@leval/mcp-grafana
GitHub Issues（在GitHub上用于讨论和报告问题的功能）： github.com/levalhq/mcp-grafana/issues 的中文翻译可以是：“GitHub 上 levalhq/mcp-grafana 项目的 Issues（问题）页面”
文档: Grafana 文档
MCP协议： modelcontextprotocol.io

🎉 致谢

这个TypeScript实现提供了与原始Go版本完全相同的功能，同时增强了与npm生态系统的集成，并支持所有主要的MCP客户端。

为Grafana和AI社区倾心打造

使用说明

@leval/mcp-grafana（这个名称在中文中没有直接的翻译，因为它是一个特定的项目或模块名称，但可以解释为“leval项目的MCP-Grafana组件”或“leval中的MCP与Grafana集成模块”，具体翻译需根据上下文确定）

🚀 功能

📦 安装

选项1：全局安装

选项2：使用npx运行（无需安装）

选项3：本地开发

🔧 配置

环境变量

🤖 MCP 客户端配置

Claude 桌面版

Claude 扩展（VS Code 扩展）

光标

泽德（Zed）

Codex（GitHub Copilot 工作区）

Continue.dev（可译为“继续开发平台”或根据具体语境灵活翻译，但“Continue.dev”本身作为专有名词，直译为“继续点开发”并不准确，需结合上下文理解其实际含义）

风帆冲浪

📚 可用工具（共43个）

仪表盘管理（5种工具）

数据来源（3种工具）

Prometheus（5种工具）

Loki 日志（5种工具）

事件管理（4种工具）

附加类别

🔒 安全

创建服务帐户令牌（推荐）

最佳实践

🧪 测试

快速测试

运行测试套件

📊 性能

🐛 故障排除

MCP服务器无法启动

连接问题

客户端未检测到服务器

常见的错误信息

📈 高级配置

禁用特定工具类别

自定义TLS配置

调试模式

🤝 贡献

功能状态

📄 许可证

📦 NPM 包

🆘 支持

🎉 致谢

相关 MCP

DuckDuckGo 搜索 MCP 服务器

图表生成MCP服务器

AI开发助手

必应中文搜索MCP服务器

PostgreSQL管理服务器

网页内容获取工具