AI导哈

Grafana MCP 服务器

Grafana MCP Server 是一个提供 AI 支持的 Grafana 集成服务器，通过标准化的 MCP 工具实现与 Grafana 实例的程序化交互，包括仪表盘管理、数据源查询、指标分析、日志搜索、警报管理和系统管理等功能。

  • by quanticsoul4772
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 quanticsoul4772/grafana-mcp

使用说明

Grafana MCP服务器

一个模型上下文协议（MCP）服务器，提供与Grafana实例的AI集成。此服务器通过标准化的MCP工具公开Grafana的全面功能，实现与仪表板、数据源、指标、日志、警报和管理功能的程序化交互。

特性

  • 52 MCP工具 跨越8个类别，实现Grafana的完整集成
  • 仪表板管理 -搜索、创建、更新和分析仪表板
  • 普罗米修斯集成 -执行PromQL查询并探索指标
  • 洛基集成 -使用LogQL搜索日志并管理日志流
  • 警报和事件响应 -管理警报规则和通知
  • 管理工具 -用户、团队和组织管理
  • 安全第一设计 -自动凭证净化和错误分类
  • TypeScript卓越 -启用严格模式的全类型安全

安装

先决条件

  • 支持ES模块的Node.js 18+
  • TypeScript 4.9+
  • 访问Grafana实例（v8.0+）

设置

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

# Install dependencies
npm install

# Build the project
npm run build

配置

环境变量

创建一个 .env 文件或设置这些环境变量：

# Required Configuration
GRAFANA_URL=https://your-grafana-instance.com
GRAFANA_TOKEN=your-service-account-token-or-api-key

# Optional Configuration
GRAFANA_DEBUG=false                    # Enable debug logging
GRAFANA_TIMEOUT=30000                  # HTTP timeout in milliseconds
GRAFANA_DISABLE_TOOLS=admin,alerting   # Disable specific tool categories

# TLS Configuration (Optional)
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          # Skip certificate verification (insecure)

认证

服务器支持多种身份验证方法：

  1. 服务帐户令牌 （推荐）

    GRAFANA_TOKEN=glsa_xxxxxxxxxxxxxxxxxxxx

  2. API密钥 （遗产）

    GRAFANA_TOKEN=eyJrIjoi...

  3. 基本认证

    GRAFANA_TOKEN=admin:password

用法

发展

# Start development server with hot reload
npm run dev

# Run tests
npm test

# Lint and format code
npm run lint
npm run format

生产

# Build and start production server
npm run build
npm start

MCP客户端集成

配置您的MCP客户端（例如Claude Desktop）以使用此服务器：

{
  "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"
      }
    }
  }
}

可用工具

仪表板工具（8个工具）

  • search_dashboards -按标题、标签或元数据查找仪表板
  • get_dashboard_by_uid -检索完整的仪表板详细信息
  • get_dashboard_panel_queries -从所有面板中提取查询
  • update_dashboard -创建或更新仪表板
  • get_dashboard_versions -查看仪表板版本历史记录
  • restore_dashboard_version -还原到特定版本
  • delete_dashboard -删除仪表板

普罗米修斯工具（6个工具）

  • query_prometheus -执行PromQL查询
  • get_prometheus_metadata -列出可用指标
  • get_prometheus_labels -获取标签名称
  • get_prometheus_label_values -获取特定标签的值
  • get_prometheus_series -查找时间序列
  • build_prometheus_query -交互式查询生成器

洛基工具（6个工具）

  • query_loki -执行LogQL查询
  • get_loki_labels -获取日志流标签
  • get_loki_label_values -获取标签值
  • get_loki_series -查找日志系列
  • build_logql_query -LogQL查询生成器
  • get_loki_stats -摄入统计

数据源工具（4个工具）

  • list_datasources -列出所有已配置的数据源
  • get_datasource_by_uid -获取特定数据源详细信息
  • test_datasource -测试数据源连接
  • query_datasource -对任何数据源执行查询

管理工具（8个工具）

  • list_users -列出组织用户
  • get_current_user -获取当前用户信息
  • list_teams -列出团队
  • get_team_by_uid -获取团队详细信息
  • list_folders -列出仪表板文件夹
  • get_folder_by_uid -获取文件夹详细信息
  • list_api_keys -列出API密钥
  • list_service_accounts -列出服务帐户

警报工具（8个工具）

  • list_alert_rules -列出所有警报规则
  • get_alert_rule_by_uid -获取特定的警报规则
  • create_alert_rule -创建新的警报规则
  • update_alert_rule -更新现有规则
  • delete_alert_rule -删除警报规则
  • list_notification_channels -列出通知渠道
  • test_notification_channel -测试通知送达
  • get_alert_history -查询警报历史记录

例子

仪表板搜索

// Find all dashboards tagged "monitoring" in the "Production" folder
{
  "tool": "search_dashboards",
  "arguments": {
    "query": "error",
    "tags": ["monitoring"],
    "folder": "Production",
    "limit": 10
  }
}

Prometheus查询

// Query HTTP request rate over last 5 minutes
{
  "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"
  }
}

洛基日志搜索

// Search for error logs in nginx service
{
  "tool": "query_loki",
  "arguments": {
    "query": "{job=\"nginx\"} |= \"error\" | rate([5m])",
    "datasourceUid": "loki-uid",
    "limit": 100,
    "direction": "backward"
  }
}

建筑

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   MCP Client    │    │  MCP Protocol   │    │ Grafana Instance│
│   (Claude AI)   │◄──►│     Server      │◄──►│    (REST API)   │
└─────────────────┘    └─────────────────┘    └─────────────────┘

核心组件

  • MCP服务器 (src/main.ts)-协议处理程序和工具注册表
  • HTTP客户端 (src/http-client.ts)-Grafana API通信
  • 服务 (src/services/)-每个Grafana区域的业务逻辑
  • 工具 (src/tools/)-MCP工具定义和处理程序
  • 安全 (src/security-utils.ts)-凭证清理和错误处理

安全特性

  • 自动数据净化 -所有日志和错误都会清理敏感数据
  • 错误分类 -用户安全与内部错误消息
  • TLS支持 -完整证书验证和客户端证书
  • 最低特权 -工具以最少的权限运行

部署

码头工人

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

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              # Entry point and MCP server setup
│   ├── config.ts            # Configuration management
│   ├── http-client.ts       # Grafana API client
│   ├── security-utils.ts    # Security and sanitization
│   ├── error-handler.ts     # Centralized error handling
│   ├── tool-registry.ts     # MCP tool registration
│   ├── types.ts             # TypeScript definitions
│   ├── services/            # Business logic services
│   │   ├── dashboard.ts     # Dashboard operations
│   │   ├── prometheus.ts    # Prometheus queries
│   │   ├── loki.ts          # Loki log queries
│   │   ├── alerting.ts      # Alert management
│   │   └── admin.ts         # Administrative functions
│   └── tools/               # MCP tool definitions
│       ├── dashboard.ts     # Dashboard tools
│       ├── prometheus.ts    # Prometheus tools
│       ├── loki.ts          # Loki tools
│       └── admin.ts         # Admin tools
├── build/                   # Compiled JavaScript output
├── package.json
├── tsconfig.json
├── eslint.config.js
└── README.md

NPM脚本

{
  "scripts": {
    "build": "tsc",                    // Compile TypeScript
    "dev": "tsx src/main.ts",          // Development server
    "start": "node build/main.js",     // Production server  
    "test": "vitest",                  // Run tests
    "test:coverage": "vitest --coverage", // Coverage report
    "lint": "eslint src/",             // ESLint checking
    "lint:fix": "eslint src/ --fix",   // Auto-fix issues
    "format": "prettier --write src/", // Format code
    "type-check": "tsc --noEmit"       // Type checking only
  }
}

代码规范

  • TypeScript严格模式 -全型安全执法
  • ESLint规则 -具有全面规则的零错误策略
  • 预处理格式 -一致的代码风格
  • Zod验证 -对所有输入进行运行时类型检查
  • 安全第一 -所有输出中的自动凭证净化

测试

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Run specific test file
npm test -- dashboard.test.ts

监控

调试模式

启用全面的日志记录以进行故障排除：

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 - Unable to connect to Grafana
  • 验证 GRAFANA_URL 正确且可访问
  • 检查网络连接和防火墙规则

身份验证失败

HTTP 401: Authentication failed
  • 验证 GRAFANA_TOKEN 有效且具有所需权限
  • 检查令牌过期情况，必要时重新生成

工具注册错误

Schema validation failed
  • 确保所有自定义工具使用正确的Zod模式验证
  • 检查一下 zodToJsonSchema() 包装器使用正确

获取帮助

使用TypeScript、Zod和模型上下文协议构建

相关 MCP