mcp-server-signoz

CalmoAI/mcp-server-signoz

3.4

If you are the rightful owner of mcp-server-signoz and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Signoz MCP Server is a Go-based implementation of a Model Context Protocol (MCP) server that integrates with SigNoz, an open-source observability platform.

Tools
9
Resources
0
Prompts
0

Signoz MCP Server

A Go implementation of a Model Context Protocol (MCP) server that provides seamless integration with SigNoz, an open-source observability platform. This server enables AI assistants and other MCP clients to interact with SigNoz APIs for querying dashboards, metrics, traces, logs, and more.

Features

The Signoz MCP Server provides the following tools:

  • signoz_test_connection: Verify connectivity to your Signoz instance and configuration
  • signoz_fetch_dashboards: List all available dashboards from Signoz
  • signoz_fetch_dashboard_details: Retrieve detailed information about a specific dashboard by its ID
  • signoz_fetch_dashboard_data: Fetch all panel data for a given dashboard by name and time range
  • signoz_fetch_apm_metrics: Retrieve standard APM metrics (request rate, error rate, latency, apdex) for a given service and time range
  • signoz_fetch_services: Fetch all instrumented services from Signoz with optional time range filtering
  • signoz_execute_clickhouse_query: Execute custom ClickHouse SQL queries via the Signoz API with time range support
  • signoz_execute_builder_query: Execute Signoz builder queries for custom metrics and aggregations with time range support
  • signoz_fetch_traces_or_logs: Fetch traces or logs from SigNoz using ClickHouse SQL

Architecture

This project follows Clean Architecture principles with the following structure:

ā”œā”€ā”€ cmd/server/              # Application entry point
ā”œā”€ā”€ internal/
ā”‚   ā”œā”€ā”€ domain/              # Domain models and interfaces
ā”‚   ā”œā”€ā”€ application/service/ # Application services
ā”‚   ā””ā”€ā”€ infrastructure/      # External integrations
ā”‚       ā”œā”€ā”€ config/          # Configuration management
ā”‚       ā””ā”€ā”€ signoz/          # Signoz API client
ā”œā”€ā”€ pkg/mcp/                 # MCP protocol implementation
ā”‚   ā”œā”€ā”€ transport/           # Transport layer (STDIO)
ā”‚   ā””ā”€ā”€ server/              # MCP server implementation
ā””ā”€ā”€ configs/                 # Configuration files

Prerequisites

  • Go 1.22 or later
  • Access to a SigNoz instance
  • SigNoz API key (if authentication is required)

Installation

Option 1: Build from Source

  1. Clone the repository:
git clone https://github.com/CalmoAI/mcp-server-signoz.git
cd signoz-mcp-server
  1. Install and update dependencies:
go mod tidy
  1. Build the server:
go build -o signoz-mcp-server ./cmd/server
  1. (Optional) Get the absolute path for configuration:
pwd
# This will show the full path to your binary: /path/to/signoz-mcp-server
  1. Verify the installation:
# Test that the binary runs (it will start the MCP server)
./signoz-mcp-server
# Press Ctrl+C to stop the server

Option 2: Install with Go

go install github.com/CalmoAI/mcp-server-signoz/cmd/server@latest

Configuration

The server can be configured using environment variables, configuration files, or command-line flags.

Environment Variables

ANY configuration value can be overridden using environment variables with the SIGNOZ_MCP_ prefix. This provides complete flexibility for deployment and runtime configuration.

Environment Variable Pattern
SIGNOZ_MCP_<SECTION>_<KEY>
Examples
# Core SigNoz configuration
export SIGNOZ_MCP_SIGNOZ_URL="https://your-signoz-instance.com"
export SIGNOZ_MCP_SIGNOZ_API_KEY="your-api-key"

# Logging configuration  
export SIGNOZ_MCP_LOG_LEVEL="debug"
export SIGNOZ_MCP_LOG_FORMAT="text"

# Server configuration
export SIGNOZ_MCP_SERVER_TIMEOUT="60s"
export SIGNOZ_MCP_SERVER_DEBUG="true"

# Telemetry configuration
export SIGNOZ_MCP_TELEMETRY_ENABLED="false"
Complete Environment Variable Reference

Server Configuration:

  • SIGNOZ_MCP_SERVER_NAME - Server name (default: "signoz-mcp-server")
  • SIGNOZ_MCP_SERVER_VERSION - Server version (default: "1.0.0")
  • SIGNOZ_MCP_SERVER_ENVIRONMENT - Environment (default: "development")
  • SIGNOZ_MCP_SERVER_DEBUG - Enable debug mode (default: false)
  • SIGNOZ_MCP_SERVER_TIMEOUT - Server timeout (default: "30s")

SigNoz Configuration:

  • SIGNOZ_MCP_SIGNOZ_URL - SigNoz instance URL (required)
  • SIGNOZ_MCP_SIGNOZ_API_KEY - API key for authentication
  • SIGNOZ_MCP_SIGNOZ_TIMEOUT - Request timeout (default: "30s")
  • SIGNOZ_MCP_SIGNOZ_RETRY_ATTEMPTS - Number of retry attempts (default: 3)
  • SIGNOZ_MCP_SIGNOZ_RETRY_DELAY - Initial retry delay (default: "1s")
  • SIGNOZ_MCP_SIGNOZ_MAX_RETRY_DELAY - Maximum retry delay (default: "30s")
  • SIGNOZ_MCP_SIGNOZ_TLS_ENABLED - Enable TLS (default: true)
  • SIGNOZ_MCP_SIGNOZ_TLS_SKIP_VERIFY - Skip TLS verification (default: false)
  • SIGNOZ_MCP_SIGNOZ_MAX_CONNECTIONS - Max HTTP connections (default: 100)
  • SIGNOZ_MCP_SIGNOZ_IDLE_TIMEOUT - Connection idle timeout (default: "90s")
  • SIGNOZ_MCP_SIGNOZ_KEEP_ALIVE - Keep-alive duration (default: "30s")

Logging Configuration:

  • SIGNOZ_MCP_LOG_LEVEL - Log level: debug, info, warn, error, fatal (default: "info")
  • SIGNOZ_MCP_LOG_FORMAT - Log format: json, text (default: "json")
  • SIGNOZ_MCP_LOG_OUTPUT - Log output: stdout, stderr (default: "stderr")
  • SIGNOZ_MCP_LOG_STRUCTURED - Structured logging (default: true)

Telemetry Configuration:

  • SIGNOZ_MCP_TELEMETRY_ENABLED - Enable telemetry (default: true)
  • SIGNOZ_MCP_TELEMETRY_SERVICE_NAME - Service name (default: "signoz-mcp-server")
  • SIGNOZ_MCP_TELEMETRY_SERVICE_VERSION - Service version (default: "1.0.0")
  • SIGNOZ_MCP_TELEMETRY_ENVIRONMENT - Environment (default: "development")
  • SIGNOZ_MCP_TELEMETRY_TRACE_ENDPOINT - Trace endpoint URL
  • SIGNOZ_MCP_TELEMETRY_METRICS_ENDPOINT - Metrics endpoint URL
  • SIGNOZ_MCP_TELEMETRY_SAMPLE_RATE - Sampling rate 0-1 (default: 1.0)
  • SIGNOZ_MCP_TELEMETRY_BATCH_TIMEOUT - Batch timeout (default: "5s")
  • SIGNOZ_MCP_TELEMETRY_EXPORT_TIMEOUT - Export timeout (default: "30s")
  • SIGNOZ_MCP_TELEMETRY_MAX_EXPORT_BATCH_SIZE - Max batch size (default: 512)

Cache Configuration:

  • SIGNOZ_MCP_CACHE_ENABLED - Enable caching (default: true)
  • SIGNOZ_MCP_CACHE_TTL - Cache TTL (default: "5m")
  • SIGNOZ_MCP_CACHE_MAX_ENTRIES - Max cache entries (default: 1000)
Configuration Precedence
  1. Environment Variables (highest priority)
  2. Configuration File (config.yaml)
  3. Default Values (lowest priority)

Configuration File

Create a config.yaml file in the current directory, ./configs/, or /etc/signoz-mcp-server/:

server:
  name: "signoz-mcp-server"
  version: "1.0.0"
  environment: "production"
  debug: false
  timeout: "30s"

signoz:
  url: "https://your-signoz-instance.com"
  api_key: "your-api-key"
  timeout: "30s"
  retry_attempts: 3
  retry_delay: "1s"
  max_retry_delay: "30s"
  tls_enabled: true
  tls_skip_verify: false
  max_connections: 100
  idle_timeout: "90s"
  keep_alive: "30s"

log:
  level: "info"
  format: "json"
  output: "stdout"
  structured: true

telemetry:
  enabled: true
  service_name: "signoz-mcp-server"
  service_version: "1.0.0"
  environment: "production"
  sample_rate: 1.0
  batch_timeout: "5s"
  export_timeout: "30s"
  max_export_batch_size: 512

cache:
  enabled: true
  ttl: "5m"
  max_entries: 1000

Required Configuration

The only required configuration is the Signoz URL:

  • SIGNOZ_MCP_SIGNOZ_URL or signoz.url in config file

Optional but recommended:

  • SIGNOZ_MCP_SIGNOZ_API_KEY or signoz.api_key for authenticated access

Usage

Running the Server

# Using environment variables
export SIGNOZ_MCP_SIGNOZ_URL="https://your-signoz-instance.com"
export SIGNOZ_MCP_SIGNOZ_API_KEY="your-api-key"
./signoz-mcp-server

# Using configuration file
./signoz-mcp-server

The server will start and communicate over STDIO following the MCP protocol specification.

Integration with Claude Desktop

Add the server to your Claude Desktop configuration:

{
  "mcpServers": {
    "signoz": {
      "command": "/absolute/path/to/signoz-mcp-server",
      "env": {
        "SIGNOZ_MCP_SIGNOZ_URL": "https://your-signoz-instance.com",
        "SIGNOZ_MCP_SIGNOZ_API_KEY": "your-api-key"
      }
    }
  }
}

Note: Replace /absolute/path/to/signoz-mcp-server with the full path to your built binary.

Integration with Cursor IDE

Add the server to your Cursor IDE MCP configuration. Create or update your MCP configuration file:

For macOS/Linux (~/.cursor/mcp_servers.json):

{
  "mcpServers": {
    "signoz": {
      "command": "/absolute/path/to/signoz-mcp-server",
      "env": {
        "SIGNOZ_MCP_SIGNOZ_URL": "https://your-signoz-instance.com",
        "SIGNOZ_MCP_SIGNOZ_API_KEY": "your-api-key"
      }
    }
  }
}

For Windows (%APPDATA%\Cursor\mcp_servers.json):

{
  "mcpServers": {
    "signoz": {
      "command": "C:\\absolute\\path\\to\\signoz-mcp-server.exe",
      "env": {
        "SIGNOZ_MCP_SIGNOZ_URL": "https://your-signoz-instance.com",
        "SIGNOZ_MCP_SIGNOZ_API_KEY": "your-api-key"
      }
    }
  }
}

Configuration Notes:

  • Replace /absolute/path/to/signoz-mcp-server with the full path to your built binary
  • The SIGNOZ_MCP_SIGNOZ_API_KEY is optional if your SigNoz instance doesn't require authentication
  • Ensure the binary has execute permissions (chmod +x signoz-mcp-server on Unix systems)

Using the Integration:

  1. Restart Cursor IDE after updating the configuration
  2. The SigNoz tools will be automatically available in Cursor's AI assistant
  3. You can directly ask Cursor to use SigNoz commands like:
    • "Test my SigNoz connection"
    • "Show me all dashboards from SigNoz"
    • "Get APM metrics for my-service"
    • "Execute this ClickHouse query on SigNoz"

Integration with Other MCP Clients

The server implements the standard MCP protocol and can be used with any compatible MCP client. Refer to your client's documentation for specific integration instructions.

Tool Usage Examples

Test Connection

Use the signoz_test_connection tool to verify your Signoz instance is accessible.

Fetch Dashboards

Use signoz_fetch_dashboards to get a list of all available dashboards.

Fetch Dashboard Details

Use signoz_fetch_dashboard_details with dashboard_id: "your-dashboard-id" to get detailed information about a specific dashboard.

Fetch Dashboard Data

Use signoz_fetch_dashboard_data with:
- dashboard_name: "My Dashboard"
- start_time: "2023-12-01T00:00:00Z"
- end_time: "2023-12-01T01:00:00Z"

Fetch APM Metrics

Use signoz_fetch_apm_metrics with:
- service_name: "my-service"
- start_time: "2023-12-01T00:00:00Z"
- end_time: "2023-12-01T01:00:00Z"

Execute ClickHouse Query

Use signoz_execute_clickhouse_query with:
- sql: "SELECT * FROM signoz_traces.signoz_spans WHERE service_name = 'my-service' LIMIT 100"
- start_time: "2023-12-01T00:00:00Z"
- end_time: "2023-12-01T01:00:00Z"

Development

Prerequisites

  • Go 1.22+
  • Make (optional, for using Makefile)

Setup

  1. Clone the repository
  2. Install dependencies: go mod download
  3. Run tests: go test ./...
  4. Build: go build -o signoz-mcp-server cmd/server/main.go

Project Structure

  • Domain Layer (internal/domain/): Core business logic and interfaces
  • Application Layer (internal/application/): Use cases and application services
  • Infrastructure Layer (internal/infrastructure/): External dependencies and implementations
  • Presentation Layer (pkg/mcp/): MCP protocol handling

Testing

Run the test suite:

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests with race detection
go test -race ./...

Adding New Tools

  1. Define the tool interface in internal/domain/interfaces.go
  2. Implement the business logic in internal/application/service/mcp_service.go
  3. Add the tool definition in pkg/mcp/server/server.go
  4. Add tool execution logic in the executeTool method

Security Considerations

  • API Keys: Store API keys securely using environment variables or secure configuration management
  • Network Security: Use HTTPS for Signoz connections in production
  • Input Validation: All user inputs are validated before processing
  • Rate Limiting: Built-in rate limiting to prevent API abuse
  • Error Handling: Errors are logged but sensitive information is not exposed

Performance

The server includes several performance optimizations:

  • Caching: Configurable caching for frequently accessed data
  • Connection Pooling: HTTP connection pooling for efficient Signoz API calls
  • Rate Limiting: Protection against API rate limits
  • Retry Logic: Exponential backoff for failed requests
  • Timeouts: Configurable timeouts to prevent hanging requests

Troubleshooting

Common Issues

  1. Connection Failed

    • Verify Signoz URL is correct and accessible
    • Check network connectivity
    • Ensure API key is valid (if required)

  2. Authentication Errors

    • Verify API key is correct
    • Check API key permissions in Signoz

  3. Query Failures

    • Verify time ranges are valid
    • Check dashboard/service names exist
    • Review ClickHouse query syntax

Logging

Enable debug logging for detailed troubleshooting:

export SIGNOZ_MCP_LOG_LEVEL="debug"
./signoz-mcp-server

Health Checks

Use the signoz_test_connection tool to verify server health and Signoz connectivity.

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Development Guidelines

  • Follow Go conventions and best practices
  • Write tests for new functionality
  • Update documentation for API changes
  • Use semantic commit messages
  • Ensure all tests pass before submitting

License

This project is licensed under the MIT License - see the file for details.

Support

Acknowledgments

  • SigNoz for the excellent observability platform
  • Anthropic for the Model Context Protocol specification
  • The Go community for excellent libraries and tools
  • Calmo Team for building it