signoz-mcp-server/README.md

Model Context Protocol server for SigNoz observability platform

# SigNoz MCP Server

A Model Context Protocol (MCP) server for SigNoz observability platform. This server enables Claude and other MCP clients to interact with SigNoz for monitoring, alerting, and observability tasks.

## Features

✅ **Complete SigNoz API Integration**
- 🔍 Query metrics, logs, and traces
- 📊 Access dashboards and visualizations
- 🚨 Manage alerts and notification channels
- 🖥️ Monitor infrastructure (hosts, pods, containers)
- 📈 Real-time monitoring capabilities
- 🏢 Enterprise features support

✅ **Easy Installation & Configuration**
- 🚀 One-command setup with npx
- 🔧 Support for self-hosted SigNoz instances
- 🔑 Secure API key management
- ✅ Connection validation
- 📁 Persistent configuration storage

✅ **Claude Integration Ready**
- 🤖 Full MCP protocol support
- 🛠️ 15+ specialized tools
- 📝 Rich text responses
- 🔄 Real-time data access

## Quick Start

### 1. Install and Configure

```bash
# Configure your SigNoz connection
npx signoz-mcp-server configure

# Or use direct parameters
npx signoz-mcp-server configure --url http://localhost:3301 --token your-api-key
```

### 2. Test Connection

```bash
# Validate your configuration
npx signoz-mcp-server test
```

### 3. Add to Claude Desktop

The configure command will output the configuration for Claude Desktop. Add it to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "signoz": {
      "command": "npx",
      "args": ["signoz-mcp-server"],
      "env": {
        "SIGNOZ_URL": "http://localhost:3301",
        "SIGNOZ_TOKEN": "your-api-key"
      }
    }
  }
}
```

### 4. Alternative: Environment Variables

```bash
export SIGNOZ_URL="http://localhost:3301"
export SIGNOZ_TOKEN="your-api-key"
npx signoz-mcp-server
```

## Supported SigNoz Deployments

### Self-Hosted SigNoz
- ✅ Docker Compose deployments
- ✅ Kubernetes deployments
- ✅ Custom installations
- ✅ HTTP and HTTPS endpoints

### SigNoz Cloud
- ✅ Fully supported
- ✅ Enterprise features
- ✅ SAML/SSO authentication

### Enterprise Edition
- ✅ License management
- ✅ Advanced analytics
- ✅ Anomaly detection
- ✅ Premium integrations

## Available Tools

### 🔍 **System & Health**
- `get_system_health` - Check SigNoz system status and version

### 📊 **Services & Monitoring**
- `get_services` - List services with performance metrics
- `get_service_details` - Detailed service analysis
- `get_dependency_graph` - Service dependency visualization

### 📈 **Metrics & Queries**
- `query_metrics` - Execute PromQL or metric queries
- `get_infrastructure` - Infrastructure monitoring (hosts, pods, etc.)

### 📝 **Logs & Traces**
- `search_logs` - Search and filter logs
- `get_trace` - Retrieve detailed trace information
- `start_live_tail` - Live log monitoring setup

### 📊 **Dashboards**
- `get_dashboards` - List all dashboards
- `get_dashboard` - Get specific dashboard details

### 🚨 **Alerts**
- `get_alerts` - View active alerts and rules
- `create_alert_rule` - Create new alert rules

### 🏢 **Enterprise Features**
- `get_license_info` - License and feature information

## Configuration Management

### CLI Commands

```bash
# Configure connection
npx signoz-mcp-server configure

# Test connection
npx signoz-mcp-server test

# Show current config
npx signoz-mcp-server show-config

# Reset configuration
npx signoz-mcp-server reset
```

### Configuration Options

```bash
# Interactive configuration
npx signoz-mcp-server configure

# Non-interactive with parameters
npx signoz-mcp-server configure \\
  --url http://your-signoz.com \\
  --token your-api-key \\
  --name production

# Skip connection validation
npx signoz-mcp-server configure --no-validate
```

## Usage Examples

### Getting Started with Claude

Once configured, you can ask Claude questions like:

- "Show me the current system health of SigNoz"
- "What services are running and their performance metrics?"
- "Search for error logs in the last hour"
- "Show me the dependency graph of my services"
- "Create an alert rule for high CPU usage"
- "What dashboards are available?"

### Example Queries

**System Health:**
```
What's the current status of my SigNoz instance?
```

**Service Monitoring:**
```
Show me all services and their error rates for the last 6 hours
```

**Log Analysis:**
```
Search for logs containing "error" or "exception" in the last 2 hours
```

**Infrastructure:**
```
Show me the current CPU and memory usage of all hosts
```

**Alerting:**
```
Create an alert rule for response time above 500ms
```

## API Key Setup

### Creating API Keys in SigNoz

1. **SigNoz UI Method:**
   - Go to Settings → API Keys
   - Click "Create New Key"
   - Choose appropriate role (VIEWER recommended for read-only access)
   - Copy the generated key

2. **Self-Hosted Setup:**
   ```bash
   # Access your SigNoz instance
   curl -X POST http://your-signoz:3301/api/v1/pats \\
     -H "Authorization: Bearer YOUR_JWT_TOKEN" \\
     -H "Content-Type: application/json" \\
     -d '{"name": "MCP Server", "role": "VIEWER"}'
   ```

### Recommended Permissions

- **VIEWER**: Read-only access (recommended for monitoring)
- **EDITOR**: Read/write access (for creating alerts, dashboards)
- **ADMIN**: Full access (not recommended for MCP usage)

## Troubleshooting

### Connection Issues

```bash
# Test your configuration
npx signoz-mcp-server test

# Check if SigNoz is accessible
curl -H "SIGNOZ-API-KEY: your-key" http://your-signoz:3301/api/v1/version
```

### Common Problems

1. **Invalid API Key**
   - Verify the key in SigNoz UI
   - Check key hasn't expired
   - Ensure correct permissions

2. **Connection Refused**
   - Verify SigNoz URL is correct
   - Check if SigNoz is running
   - Verify network connectivity

3. **Self-Hosted Issues**
   - Check if port 3301 is accessible
   - Verify API endpoints are enabled
   - Check authentication configuration

### Debug Mode

```bash
# Enable debug logging
DEBUG=signoz-mcp* npx signoz-mcp-server
```

## Development

### Local Development

```bash
# Clone and setup
git clone https://github.com/SigNoz/mcp-server
cd mcp-server
npm install

# Build
npm run build

# Development mode
npm run dev

# Test CLI
npm run cli configure
```

### Project Structure

```
src/
├── index.ts        # Main MCP server
├── cli.ts          # CLI tool
├── client.ts       # SigNoz API client
└── types.ts        # TypeScript definitions
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

## Support

- 📚 [SigNoz Documentation](https://signoz.io/docs/)
- 💬 [SigNoz Community](https://signoz.io/slack)
- 🐛 [Report Issues](https://github.com/SigNoz/mcp-server/issues)
- 📧 [Contact Support](https://signoz.io/support)

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Changelog

### v1.0.0
- ✅ Initial release
- ✅ Complete SigNoz API integration
- ✅ CLI configuration tool
- ✅ Self-hosted support
- ✅ Enterprise features
- ✅ 15+ MCP tools
- ✅ Real-time monitoring
- ✅ Comprehensive error handling