内容
# Grafana MCP 服务器
一个提供与 Grafana 实例的 AI 集成能力的模型上下文协议(MCP)服务器。该服务器通过标准化的 MCP 工具公开 Grafana 的全面功能,实现与仪表盘、数据源、指标、日志、警报和管理员功能的编程交互。
## 功能
- **59 个 MCP 工具**,涵盖 9 个类别,实现完整的 Grafana 集成
- **仪表盘管理** - 搜索、创建、更新和分析仪表盘
- **Prometheus 集成** - 执行 PromQL 查询和探索指标
- **Loki 集成** - 使用 LogQL 搜索日志和管理日志流
- **警报和事件响应** - 管理警报规则和通知
- **RAMP 集成** - 通过 SSH 隧道自动发现传感器,查询指标,比较基准,渲染性能裁决
- **管理员工具** - 用户、团队和组织管理
- **导航和深链接** - 为仪表盘、面板和 Explore 视图生成 URL
- **安全优先设计** - 自动凭证净化和错误分类
- **TypeScript 卓越** - 启用严格模式的完整类型安全
## 安装
### 先决条件
- Node.js 18+,支持 ES 模块
- TypeScript 4.9+
- 可以访问 Grafana 实例(v8.0+)
### 设置
```bash
# 克隆仓库
git clone https://github.com/your-org/grafana-mcp
cd grafana-mcp
# 安装依赖
npm install
# 构建项目
npm run build
```
## 配置
### 环境变量
创建 `.env` 文件或设置这些环境变量:
```bash
# 必需配置
GRAFANA_URL=https://your-grafana-instance.com
GRAFANA_TOKEN=your-service-account-token-or-api-key
# 可选配置
GRAFANA_DEBUG=false # 启用调试日志
GRAFANA_TIMEOUT=30000 # HTTP 超时(毫秒)
GRAFANA_DISABLE_TOOLS=admin,alerting # 禁用特定工具类别
# TLS 配置(可选)
GRAFANA_TLS_CERT_FILE=/path/to/client.crt
GRAFANA_TLS_KEY_FILE=/path/to/client.key
GRAFANA_TLS_CA_FILE=/path/to/ca.crt
GRAFANA_TLS_SKIP_VERIFY=false # 跳过证书验证(不安全)
```
### 认证
服务器支持多种认证方法:
1. **服务账户令牌**(推荐)
```bash
GRAFANA_TOKEN=glsa_xxxxxxxxxxxxxxxxxxxx
```
2. **API 密钥**(旧版)
```bash
GRAFANA_TOKEN=eyJrIjoi...
```
3. **基本认证**
```bash
GRAFANA_TOKEN=admin:password
```
## 用法
### 开发
```bash
# 启动带有热重载的开发服务器
npm run dev
# 运行测试
npm test
# 校验和格式化代码
npm run lint
npm run format
```
### 生产
```bash
# 构建并启动生产服务器
npm run build
npm start
```
### MCP 客户端集成
配置您的 MCP 客户端(例如 Claude Desktop)以使用此服务器:
```json
{
"mcpServers": {
"grafana": {
"command": "node",
"args": ["/path/to/grafana-mcp/build/main.js"],
"env": {
"GRAFANA_URL": "https://your-grafana.com",
"GRAFANA_TOKEN": "your-service-account-token"
}
}
}
}
```
## 可用工具
### 仪表盘工具(7 个工具)
- `search_dashboards` - 按标题、标签或元数据查找仪表盘
- `get_dashboard_by_uid` - 检索完整的仪表盘详细信息
- `get_dashboard_panel_queries` - 从所有面板中提取查询
- `update_dashboard` - 创建或更新仪表盘
- `get_dashboard_versions` - 查看仪表盘版本历史
- `restore_dashboard_version` - 恢复到特定版本
- `delete_dashboard` - 删除仪表盘
### 数据源工具(7 个工具)
- `list_datasources` - 列出所有配置的数据源
- `get_datasource_by_uid` - 按 UID 获取数据源详细信息
- `get_datasource_by_name` - 按名称获取数据源详细信息
- `test_datasource_connection` - 测试数据源连接性
- `get_datasources_by_type` - 按类型筛选数据源
- `get_default_datasource` - 获取默认数据源
- `check_datasource_exists` - 检查数据源是否存在
### Prometheus 工具(6 个工具)
- `query_prometheus` - 执行 PromQL 查询
- `get_prometheus_metadata` - 列出可用指标
- `get_prometheus_labels` - 获取标签名称
- `get_prometheus_label_values` - 获取特定标签的值
- `get_prometheus_series` - 查找时间序列
- `build_prometheus_query` - 交互式查询生成器
### Loki 工具(6 个工具)
- `query_loki` - 执行 LogQL 查询
- `get_loki_labels` - 获取日志流标签
- `get_loki_label_values` - 获取标签值
- `get_loki_series` - 查找日志序列
- `build_logql_query` - LogQL 查询生成器
- `get_loki_stats` - 写入统计信息
### 警报工具(9 个工具)
- `list_alert_rules` - 列出所有警报规则
- `get_alert_rule` - 获取特定警报规则详细信息
- `create_alert_rule` - 创建新的警报规则
- `update_alert_rule` - 更新现有规则
- `delete_alert_rule` - 删除警报规则
- `list_contact_points` - 列出通知联系点
- `get_contact_point` - 获取联系点详细信息
- `test_contact_point` - 测试通知传递
- `list_alert_rule_groups` - 列出警报规则组
### 管理工具(9 个工具)
- `list_teams` - 列出团队
- `get_team_by_uid` - 获取团队详细信息
- `list_users` - 列出组织用户
- `get_current_user` - 获取当前用户信息
- `list_folders` - 列出仪表盘文件夹
- `get_folder_by_uid` - 获取文件夹详细信息
- `list_api_keys` - 列出 API 密钥
- `list_service_accounts` - 列出服务账户
- `get_current_organization` - 获取当前组织信息
### 导航工具(8 个工具)
- `generate_deeplink` - 为仪表盘、面板或 Explore 生成深链接 URL
- `generate_dashboard_url` - 生成带有时间范围和变量的仪表盘 URL
- `generate_panel_url` - 生成面板特定 URL
- `generate_explore_url` - 生成 Explore 视图 URL
- `generate_prometheus_explore_url` - 生成 Prometheus Explore URL
- `generate_loki_explore_url` - 生成 Loki Explore URL
- `get_time_range_presets` - 获取常见时间范围预设
- `validate_time_range` - 验证时间范围参数
### RAMP 工具(7 个工具)
- `discover_sensors` - 通过 SSH 隧道自动发现 Corelight 传感器(端口 8080-8099)
- `sensor_status` - 获取传感器的健康和版本信息
- `query_sensor_metric` - 从传感器的 Grafana 查询 Prometheus 指标
- `deploy_ramp_dashboard` - 将标准 RAMP 仪表盘部署到传感器
- `list_baselines` - 列出可用于比较的性能基准
- `sensor_performance_verdict` - 将当前指标与基准(通过/边缘/失败)进行比较
- `annotate_test` - 创建 Grafana 注释以标记测试事件
## 示例
### 仪表盘搜索
```typescript
// 查找生产环境中所有标记为“monitoring”的仪表盘
{
"tool": "search_dashboards",
"arguments": {
"query": "error",
"tags": ["monitoring"],
"folder": "Production",
"limit": 10
}
}
```
### Prometheus 查询
```typescript
// 查询过去 5 分钟的 HTTP 请求速率
{
"tool": "query_prometheus",
"arguments": {
"query": "rate(http_requests_total[5m])",
"datasourceUid": "prometheus-uid",
"start": "2024-01-01T00:00:00Z",
"end": "2024-01-01T01:00:00Z"
}
}
```
### Loki 日志搜索
```typescript
// 在 nginx 服务中搜索错误日志
{
"tool": "query_loki",
"arguments": {
"query": "{job=\"nginx\"} |= \"error\" | rate([5m])",
"datasourceUid": "loki-uid",
"limit": 100,
"direction": "backward"
}
}
```
## 架构
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ MCP 客户端 │ │ MCP 协议 │ │ Grafana 实例 │
│ (Claude AI) │◄──►│ 服务器 │◄──►│ (REST API) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
### 核心组件
- **MCP 服务器** (`src/main.ts`) - 协议处理程序和工具注册表
- **HTTP 客户端** (`src/http-client.ts`) - Grafana API 通信
- **服务** (`src/services/`) - 每个 Grafana 领域的业务逻辑
- **工具** (`src/tools/`) - MCP 工具定义和处理程序
- **安全** (`src/security-utils.ts`) - 凭证净化和错误处理
### 安全功能
- **自动数据净化** - 所有日志和错误都净化敏感数据
- **错误分类** - 用户安全与内部错误消息
- **TLS 支持** - 完整的证书验证和客户端证书
- **最小权限** - 工具以最小所需权限运行
## 部署
### Docker
```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY build/ ./build/
EXPOSE 3000
CMD ["node", "build/main.js"]
```
### Docker Compose
```yaml
version: '3.8'
services:
grafana-mcp:
build: .
environment:
- GRAFANA_URL=https://your-grafana.com
- GRAFANA_TOKEN=${GRAFANA_TOKEN}
- GRAFANA_DEBUG=false
volumes:
- ./logs:/app/logs
```
## 开发
### 项目结构
```
grafana-mcp/
├── src/
│ ├── main.ts # 入口点和 MCP 服务器设置
│ ├── config.ts # 配置管理
│ ├── http-client.ts # Grafana API 客户端
│ ├── security-utils.ts # 安全和净化
│ ├── error-handler.ts # 集中错误处理
│ ├── tool-registry.ts # MCP 工具注册
│ ├── types.ts # TypeScript 定义
│ ├── core/ # 基类和接口
│ │ ├── base-service.ts # 具有执行/健康模式的基服务
│ │ └── interfaces.ts # 服务和 HTTP 接口
│ ├── services/ # 业务逻辑服务
│ │ ├── dashboard.ts # 仪表盘操作
│ │ ├── datasource.ts # 数据源管理
│ │ ├── prometheus.ts # Prometheus 查询
│ │ ├── loki.ts # Loki 日志查询
│ │ ├── alerting.ts # 警报管理
│ │ ├── admin.ts # 管理功能
│ │ ├── navigation.ts # URL 和深链接生成
│ │ └── ramp.ts # RAMP 传感器发现和指标
│ └── tools/ # MCP 工具定义
│ ├── dashboard.ts # 仪表盘工具
│ ├── datasource.ts # 数据源工具
│ ├── prometheus.ts # Prometheus 工具
│ ├── loki.ts # Loki 工具
│ ├── alerting.ts # 警报工具
│ ├── admin.ts # 管理工具
│ ├── navigation.ts # 导航工具
│ └── ramp.ts # RAMP 工具
├── build/ # 编译的 JavaScript 输出
├── package.json
├── tsconfig.json
├── eslint.config.ts
└── README.md
```
### NPM 脚本
```json
{
"scripts": {
"build": "tsc", # 编译 TypeScript
"dev": "tsx src/main.ts", # 开发服务器
"start": "node build/main.js", # 生产服务器
"test": "vitest", # 运行测试
"test:coverage": "vitest --coverage", # 覆盖率报告
"lint": "eslint src/", # ESLint 检查
"lint:fix": "eslint src/ --fix", # 自动修复问题
"format": "prettier --write src/", # 格式化代码
"type-check": "tsc --noEmit" # 类型检查
}
}
```
### 代码标准
- **TypeScript 严格模式** - 完整的类型安全强制
- **ESLint 规则** - 零错误策略,全面规则
- **Prettier 格式化** - 一致的代码风格
- **Zod 验证** - 所有输入的运行时类型检查
- **安全优先** - 所有输出的自动凭证净化
## 测试
```bash
# 运行所有测试
npm test
# 运行测试并生成覆盖率报告
npm run test:coverage
# 以监视模式运行测试
npm run test:watch
# 运行特定测试文件
npm test -- dashboard.test.ts
```
## 监控
### 调试模式
启用全面日志记录进行故障排除:
```bash
GRAFANA_DEBUG=true npm start
```
调试输出包括:
- HTTP 请求/响应详细信息(净化)
- 工具执行跟踪
- 错误分类详细信息
- 性能指标
### 健康检查
服务器通过以下方式提供健康信息:
- 进程退出代码
- 分类错误日志
- 连接状态监控
## 贡献
我们欢迎贡献!请参阅我们的贡献指南:
1. **分叉和克隆** - 创建您的功能分支
2. **代码标准** - 遵循 TypeScript 严格模式和 ESLint 规则
3. **测试** - 为新功能添加测试
4. **安全** - 包括安全影响评估
5. **文档** - 更新新功能的文档
### 拉取请求检查清单
- [ ] 所有测试通过 (`npm test`)
- [ ] 无 ESLint 错误 (`npm run lint`)
- [ ] 代码格式化 (`npm run format`)
- [ ] TypeScript 编译 (`npm run type-check`)
- [ ] 文档更新
- [ ] 安全考虑
## 许可证
[待添加许可信息]
## 支持
### 常见问题
**连接错误**
```
Error: ECONNREFUSED - 无法连接到 Grafana
```
- 验证 `GRAFANA_URL` 是否正确且可访问
- 检查网络连接性和防火墙规则
**认证失败**
```
HTTP 401: 认证失败
```
- 验证 `GRAFANA_TOKEN` 是否有效且具有所需权限
- 检查令牌过期并在需要时重新生成
**工具注册错误**
```
模式验证失败
```
- 确保所有自定义工具都使用正确的 Zod 模式验证
- 检查 `zodToJsonSchema()` 包装器是否正确使用
### 获取帮助
- 查看 [故障排除指南](docs/troubleshooting.md)
- 查看 [API 文档](docs/api.md)
- 为 bug 或功能请求打开问题
---
**使用 TypeScript、Zod 和模型上下文协议构建**
连接信息
猜你喜欢
暂无推荐服务器