Content
# Grafana MCP Server
A Model Context Protocol (MCP) server that provides AI-powered integration with Grafana instances. This server exposes Grafana's comprehensive functionality through standardized MCP tools, enabling programmatic interaction with dashboards, data sources, metrics, logs, alerting, and administrative functions.
## Features
- **52 MCP Tools** across 8 categories for complete Grafana integration
- **Dashboard Management** - Search, create, update, and analyze dashboards
- **Prometheus Integration** - Execute PromQL queries and explore metrics
- **Loki Integration** - Search logs with LogQL and manage log streams
- **Alerting & Incident Response** - Manage alert rules and notifications
- **Administrative Tools** - User, team, and organization management
- **Security-First Design** - Automatic credential sanitization and error categorization
- **TypeScript Excellence** - Full type safety with strict mode enabled
## Installation
### Prerequisites
- Node.js 18+ with ES modules support
- TypeScript 4.9+
- Access to a Grafana instance (v8.0+)
### Setup
```bash
# 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
```
## Configuration
### Environment Variables
Create a `.env` file or set these environment variables:
```bash
# 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)
```
### Authentication
The server supports multiple authentication methods:
1. **Service Account Tokens** (Recommended)
```bash
GRAFANA_TOKEN=glsa_xxxxxxxxxxxxxxxxxxxx
```
2. **API Keys** (Legacy)
```bash
GRAFANA_TOKEN=eyJrIjoi...
```
3. **Basic Authentication**
```bash
GRAFANA_TOKEN=admin:password
```
## Usage
### Development
```bash
# Start development server with hot reload
npm run dev
# Run tests
npm test
# Lint and format code
npm run lint
npm run format
```
### Production
```bash
# Build and start production server
npm run build
npm start
```
### MCP Client Integration
Configure your MCP client (e.g., Claude Desktop) to use this server:
```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"
}
}
}
}
```
## Available Tools
### Dashboard Tools (8 tools)
- `search_dashboards` - Find dashboards by title, tags, or metadata
- `get_dashboard_by_uid` - Retrieve complete dashboard details
- `get_dashboard_panel_queries` - Extract queries from all panels
- `update_dashboard` - Create or update dashboards
- `get_dashboard_versions` - View dashboard version history
- `restore_dashboard_version` - Restore to a specific version
- `delete_dashboard` - Remove dashboards
### Prometheus Tools (6 tools)
- `query_prometheus` - Execute PromQL queries
- `get_prometheus_metadata` - List available metrics
- `get_prometheus_labels` - Get label names
- `get_prometheus_label_values` - Get values for specific labels
- `get_prometheus_series` - Find time series
- `build_prometheus_query` - Interactive query builder
### Loki Tools (6 tools)
- `query_loki` - Execute LogQL queries
- `get_loki_labels` - Get log stream labels
- `get_loki_label_values` - Get label values
- `get_loki_series` - Find log series
- `build_logql_query` - LogQL query builder
- `get_loki_stats` - Ingestion statistics
### Data Source Tools (4 tools)
- `list_datasources` - List all configured data sources
- `get_datasource_by_uid` - Get specific data source details
- `test_datasource` - Test data source connectivity
- `query_datasource` - Execute queries against any data source
### Admin Tools (8 tools)
- `list_users` - List organization users
- `get_current_user` - Get current user info
- `list_teams` - List teams
- `get_team_by_uid` - Get team details
- `list_folders` - List dashboard folders
- `get_folder_by_uid` - Get folder details
- `list_api_keys` - List API keys
- `list_service_accounts` - List service accounts
### Alerting Tools (8 tools)
- `list_alert_rules` - List all alert rules
- `get_alert_rule_by_uid` - Get specific alert rule
- `create_alert_rule` - Create new alert rules
- `update_alert_rule` - Update existing rules
- `delete_alert_rule` - Delete alert rules
- `list_notification_channels` - List notification channels
- `test_notification_channel` - Test notification delivery
- `get_alert_history` - Query alert history
## Examples
### Dashboard Search
```typescript
// Find all dashboards tagged "monitoring" in the "Production" folder
{
"tool": "search_dashboards",
"arguments": {
"query": "error",
"tags": ["monitoring"],
"folder": "Production",
"limit": 10
}
}
```
### Prometheus Query
```typescript
// 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"
}
}
```
### Loki Log Search
```typescript
// Search for error logs in nginx service
{
"tool": "query_loki",
"arguments": {
"query": "{job=\"nginx\"} |= \"error\" | rate([5m])",
"datasourceUid": "loki-uid",
"limit": 100,
"direction": "backward"
}
}
```
## Architecture
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ MCP Client │ │ MCP Protocol │ │ Grafana Instance│
│ (Claude AI) │◄──►│ Server │◄──►│ (REST API) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
### Core Components
- **MCP Server** (`src/main.ts`) - Protocol handler and tool registry
- **HTTP Client** (`src/http-client.ts`) - Grafana API communication
- **Services** (`src/services/`) - Business logic for each Grafana area
- **Tools** (`src/tools/`) - MCP tool definitions and handlers
- **Security** (`src/security-utils.ts`) - Credential sanitization and error handling
### Security Features
- **Automatic Data Sanitization** - All logs and errors sanitize sensitive data
- **Error Categorization** - User-safe vs internal error messaging
- **TLS Support** - Full certificate validation and client certificates
- **Minimal Privilege** - Tools operate with least required permissions
## Deployment
### 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
```
## Development
### Project Structure
```
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
```json
{
"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
}
}
```
### Code Standards
- **TypeScript Strict Mode** - Full type safety enforcement
- **ESLint Rules** - Zero-error policy with comprehensive rules
- **Prettier Formatting** - Consistent code style
- **Zod Validation** - Runtime type checking for all inputs
- **Security First** - Automatic credential sanitization in all outputs
## Testing
```bash
# 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
```
## Monitoring
### Debug Mode
Enable comprehensive logging for troubleshooting:
```bash
GRAFANA_DEBUG=true npm start
```
Debug output includes:
- HTTP request/response details (sanitized)
- Tool execution traces
- Error categorization details
- Performance metrics
### Health Checks
The server provides health information through:
- Process exit codes
- Error logs with categorization
- Connection status monitoring
## Contributing
We welcome contributions! Please see our contributing guidelines:
1. **Fork and Clone** - Create your feature branch
2. **Code Standards** - Follow TypeScript strict mode and ESLint rules
3. **Testing** - Add tests for new functionality
4. **Security** - Include security impact assessment
5. **Documentation** - Update docs for new features
### Pull Request Checklist
- [ ] All tests pass (`npm test`)
- [ ] No ESLint errors (`npm run lint`)
- [ ] Code formatted (`npm run format`)
- [ ] TypeScript compiles (`npm run type-check`)
- [ ] Documentation updated
- [ ] Security considerations addressed
## License
[License information to be added]
## Support
### Common Issues
**Connection Errors**
```
Error: ECONNREFUSED - Unable to connect to Grafana
```
- Verify `GRAFANA_URL` is correct and accessible
- Check network connectivity and firewall rules
**Authentication Failures**
```
HTTP 401: Authentication failed
```
- Verify `GRAFANA_TOKEN` is valid and has required permissions
- Check token expiration and regenerate if needed
**Tool Registration Errors**
```
Schema validation failed
```
- Ensure all custom tools use proper Zod schema validation
- Check that `zodToJsonSchema()` wrapper is used correctly
### Getting Help
- Check the [troubleshooting guide](docs/troubleshooting.md)
- Review [API documentation](docs/api.md)
- Open an issue for bugs or feature requests
---
**Built with TypeScript, Zod, and the Model Context Protocol**
