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

# 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

# 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:

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

4. Alternative: Environment Variables

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

# 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

# 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:

   # 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

# 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

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

Development

Local Development

# 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
• 💬 SigNoz Community
• 🐛 Report Issues
• 📧 Contact Support

License

MIT License - see 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