Built by Metorial, the integration platform for agentic AI.

Learn More

SigNoz

SigNoz MCP Server

SigNoz MCP Server

Go Version License MCP Version

A Model Context Protocol (MCP) server that provides seamless access to SigNoz observability data through AI assistants and LLMs. This server enables natural language queries for metrics, traces, logs, alerts, dashboards, and service performance data.

🚀 Features

  • List Metric Keys: Retrieve all available metric keys from SigNoz.
  • Search Metric by text: Find specific metric containing given text.
  • List Alerts: Get all active alerts with detailed status.
  • Get Alert Details: Retrieve comprehensive information about specific alert rules.
  • Get Alert History: Gives you timeline of an alert.
  • Logs: Search, aggregate, and analyze logs with flexible filtering.
  • Traces: Search, aggregate, analyze, get hierarchy and relationship of traces.
  • List Dashboards: Get dashboard summaries (name, UUID, description, tags).
  • Get Dashboard: Retrieve complete dashboard configurations with panels and queries.
  • Create Dashboard: Creates a new monitoring dashboard based on the provided title, layout, and widget configuration. Warning: Requires full dashboard JSON which can consume large amounts of context window space.
  • Update Dashboard: Updates an existing dashboard using its UUID and a complete dashboard JSON object. Requires the entire post-update configuration and cannot accept partial patches.
  • List Services: Discover all services within specified time ranges.
  • Service Top Operations: Analyze performance metrics for specific services.
  • Query Builder: Generates query to get complex response.

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │───▶│  MCP Server      │───▶│   SigNoz API    │
│  (AI Assistant) │    │  (Go)            │    │  (Observability)│
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌──────────────────┐
                       │   Tool Handlers  │
                       │  (HTTP Client)   │
                       └──────────────────┘

Core Components

  • MCP Server: Handles MCP protocol communication
  • Tool Handlers: Register and manage available tools
  • SigNoz Client: HTTP client for SigNoz API interactions
  • Configuration: Environment-based configuration management
  • Logging: Structured logging with Zap

🧰 Usage

Use this mcp-server with MCP-compatible clients like Claude Desktop and Cursor.

Claude Desktop

  1. Build or locate the binary path for signoz-mcp-server (for example: .../signoz-mcp-server/bin/signoz-mcp-server).
  2. Goto Claude -> Settings -> Developer -> Local MCP Server click on edit config
  3. Edit claude_desktop_config.json Add shown config with your signoz url, api key and path to signoz-mcp-server binary.
{
    "mcpServers": {
        "signoz": {
            "command": "/absolute/path/to/signoz-mcp-server/bin/signoz-mcp-server",
            "args": [],
            "env": {
                "SIGNOZ_URL": "https://your-signoz-instance.com",
                "SIGNOZ_API_KEY": "your-api-key-here",
                "LOG_LEVEL": "info"
            }
        }
    }
}
  1. Restart Claude Desktop. You should see the signoz server load in the developer console and its tools become available.

Notes:

  • Replace the command path with your actual binary location.

Cursor

Option A — GUI:

  • Open Cursor → Settings → Cursor Settings → Tool & Integrations → + New MCP Server

Option B — Project config file: Create .cursor/mcp.json in your project root:

For Both options use same json struct

{
    "mcpServers": {
        "signoz": {
            "command": "/absolute/path/to/signoz-mcp-server/bin/signoz-mcp-server",
            "args": [],
            "env": {
                "SIGNOZ_URL": "https://your-signoz-instance.com",
                "SIGNOZ_API_KEY": "your-api-key-here",
                "LOG_LEVEL": "info"
            }
        }
    }
}

Once added, restart Cursor to use the SigNoz tools.

HTTP based self hosted mcp server

Claude Desktop

  1. Build and run signoz-mcp-server with envs
    • SIGNOZ_URL=signoz_url SIGNOZ_API_KEY=signoz_apikey TRANSPORT_MODE=http MCP_SERVER_PORT=8000 LOG_LEVEL=log_level ./signoz-mcp-server
    • or use docker-compose
  2. Goto Claude -> Settings -> Developer -> Local MCP Server click on edit config
  3. Edit claude_desktop_config.json Add shown config with your signoz url, api key and path to signoz-mcp-server binary.
{
    "mcpServers": {
        "signoz": {
            "url": "http://localhost:8000/mcp",
            "headers": {
                "Authorization": "Bearer your-api-key-here"
            }
        }
    }
}

Note: You can pass the SigNoz API key either as:

  • An environment variable (SIGNOZ_API_KEY) when starting the server, or
  • Via the Authorization header in the client configuration as shown above
  1. Restart Claude Desktop. You should see the signoz server load in the developer console and its tools become available.

Cursor

Build and run signoz-mcp-server with envs - SIGNOZ_URL=signoz_url SIGNOZ_API_KEY=signoz_apikey TRANSPORT_MODE=http MCP_SERVER_PORT=8000 LOG_LEVEL=log_level ./signoz-mcp-server - or use docker-compose

Option A — GUI:

  • Open Cursor → Settings → Cursor Settings → Tool & Integrations → + New MCP Server

Option B — Project config file: Create .cursor/mcp.json in your project root:

For Both options use same json struct

{
    "mcpServers": {
        "signoz": {
            "url": "http://localhost:8000/mcp",
            "headers": {
                "Authorization": "Bearer signoz-api-key-here"
            }
        }
    }
}

Note: You can pass the SigNoz API key either as:

  • An environment variable (SIGNOZ_API_KEY) when starting the server, or
  • Via the Authorization header in the client configuration as shown above

Note: By default, the server logs at info level. If you need detailed debugging information, set LOG_LEVEL=debug in your environment. For production use, consider using LOG_LEVEL=warn to reduce log verbosity.

🛠️ Development Guide

Prerequisites

  • Go 1.25 or higher
  • SigNoz instance with API access
  • Valid SigNoz API key

Project Structure

signoz-mcp-server/
├── cmd/server/           # Main application entry point
├── internal/
│   ├── client/          # SigNoz API client
│   ├── config/          # Configuration management
│   ├── handler/tools/   # MCP tool implementations
│   ├── logger/          # Logging utilities
│   └── mcp-server/      # MCP server core
├── go.mod               # Go module dependencies
├── Makefile             # Build automation
└── README.md

Building from Source

# Clone the repository
git clone https://github.com/SigNoz/signoz-mcp-server.git
cd signoz-mcp-server

# Build the binary
make build

# Or build directly with Go
go build -o bin/signoz-mcp-server ./cmd/server/

Configuration

Set the following environment variables:


export SIGNOZ_URL="https://your-signoz-instance.com"
export SIGNOZ_API_KEY="your-api-key-here"
export LOG_LEVEL="info"  # Optional: debug, info, error (default: info)

In SigNoz Cloud, SIGNOZ_URL is typically - https://ingest..signoz.cloud

You can access API Key by going to Settings -> Workspace Settings -> API Key in SigNoz UI

Running the Server

# Run the built binary
./bin/signoz-mcp-server

Development Workflow

  1. Add New Tools: Implement in internal/handler/tools/
  2. Extend Client: Add methods to internal/client/client.go
  3. Register Tools: Add to appropriate handler registration
  4. Test: Use MCP client to verify functionality

📖 User Guide

For AI Assistants & LLMs

The MCP server provides the following tools that can be used through natural language:

Metrics Exploration

"Show me all available metrics"
"Search for CPU related metrics"

Alert Monitoring

"List all active alerts"
"Get details for alert rule ID abc123"
"Show me the history for alert rule abc123 from the last 6 hours"
"Get logs related to alert abc456"

Dashboard Management

"List all dashboards"
"Show me the Host Metrics dashboard details"
"Create a dashboard with a specified name, optional tags, and a widget visualizing a chosen metric."

Service Analysis

"List all services from the last 6 hours"
"What are the top operations for the paymentservice?"

Log Analysis

"List all saved log views"
"Show me error logs for the paymentservice from the last hour"
"Search paymentservice logs for 'connection timeout' errors"
"Get error logs with FATAL severity"
"How many errors per service in the last hour?"
"What are the top error messages for the consumer service?"
"Search all logs where workflow_run_id = 'wr_123'"
"Show me logs containing 'timeout' across all services"

Trace Analysis

"Show me all available trace fields"
"Search traces for the apple service from the last hour"
"Get details for trace ID ball123"
"Check for  error patterns in traces from the randomservice"
"Show me the span hierarchy for trace xyz789"
"Find traces with errors in the last 2 hours"
"Give me flow of this trace"
"What is the p99 latency for the checkout service?"
"How many errors per service in the last hour?"
"Average response time by operation for the payment-svc"
"Request rate per service in the last 30 minutes"
"Which operations have the highest p95 latency?"

Tool Reference

signoz_list_metric_keys

Lists all available metric keys from SigNoz.

signoz_search_metric_by_text

Searches metrics by text (uses SigNoz aggregate_attributes autocomplete).

  • Parameters: searchText (required) - Text to search for

signoz_list_alerts

Lists all active alerts from SigNoz.

signoz_get_alert

Gets details of a specific alert rule.

  • Parameters: ruleId (required) - Alert rule ID

signoz_list_dashboards

Lists all dashboards with summaries (name, UUID, description, tags).

  • Returns: Simplified dashboard information for better LLM processing

signoz_get_dashboard

Gets complete dashboard configuration.

  • Parameters: uuid (required) - Dashboard UUID

signoz_create_dashboard

Creates a dashboard.

  • Parameters:
    • title (required) – Dashboard name
    • description (optional) – Short summary of what the dashboard shows
    • tags (optional) – List of tags
    • layout (required) – Widget positioning grid
    • variables (optional) – Map of variables available for use in queries
    • widgets (required) – List of widgets added to the dashboard
  • Returns Dashboard metadata, layout array, widgets array, and stored dashboard config.

signoz_update_dashboard

Updates an existing dashboard.

  • Parameters
    • uuid (required) – Unique identifier of the dashboard to update
    • title (required) – Dashboard name
    • description (optional) – Short summary of what the dashboard shows
    • tags (optional) – List of tags applied to the dashboard
    • layout (required) – Full widget positioning grid
    • variables (optional) – Map of variables available for use in queries
    • widgets (required) – Complete set of widgets defining the updated dashboard

Returns A success confirmation only. No response body is provided.

signoz_list_services

Lists all services within a time range.

  • Parameters:
    • timeRange (optional) - Time range like '2h', '6h', '2d', '7d'
    • start (optional) - Start time in nanoseconds (defaults to 6 hours ago)
    • end (optional) - End time in nanoseconds (defaults to now)

signoz_get_service_top_operations

Gets top operations for a specific service.

  • Parameters:
    • service (required) - Service name
    • timeRange (optional) - Time range like '2h', '6h', '2d', '7d'
    • start (optional) - Start time in nanoseconds (defaults to 6 hours ago)
    • end (optional) - End time in nanoseconds (defaults to now)
    • tags (optional) - JSON array of tags

signoz_get_alert_history

Gets alert history timeline for a specific rule.

  • Parameters:
    • ruleId (required) - Alert rule ID
    • timeRange (optional) - Time range like '2h', '6h', '2d', '7d'
    • start (optional) - Start timestamp in milliseconds (defaults to 6 hours ago)
    • end (optional) - End timestamp in milliseconds (defaults to now)
    • offset (optional) - Offset for pagination (default: 0)
    • limit (optional) - Limit number of results (default: 20)
    • order (optional) - Sort order: 'asc' or 'desc' (default: 'asc')

signoz_list_log_views

Lists all saved log views from SigNoz.

  • Returns: Summary with name, ID, description, and query details

signoz_get_log_view

Gets full details of a specific log view by ID.

  • Parameters: viewId (required) - Log view ID

signoz_get_logs_for_alert

Gets logs related to a specific alert automatically.

  • Parameters:
    • alertId (required) - Alert rule ID
    • timeRange (optional) - Time range around alert (e.g., '1h', '30m', '2h') - default: '1h'
    • limit (optional) - Maximum number of logs to return (default: 100)

signoz_get_error_logs

Gets logs with ERROR or FATAL severity within a time range.

  • Parameters:
    • timeRange (optional) - Time range like '2h', '6h', '2d', '7d'
    • start (optional) - Start time in milliseconds (defaults to 6 hours ago)
    • end (optional) - End time in milliseconds (defaults to now)
    • service (optional) - Service name to filter by
    • limit (optional) - Maximum number of logs to return (default: 100)

signoz_search_logs_by_service

Searches logs for a specific service within a time range.

  • Parameters:
    • service (required) - Service name to search logs for
    • timeRange (optional) - Time range like '2h', '6h', '2d', '7d'
    • start (optional) - Start time in milliseconds (defaults to 6 hours ago)
    • end (optional) - End time in milliseconds (defaults to now)
    • severity (optional) - Log severity filter (DEBUG, INFO, WARN, ERROR, FATAL)
    • searchText (optional) - Text to search for in log body
    • limit (optional) - Maximum number of logs to return (default: 100)

signoz_aggregate_logs

Aggregate logs to provide count, average, sum, min, max, or percentiles, optionally grouped by fields. Use this for questions like "how many errors per service?", "average response time by endpoint", or "top error messages by count".

  • Parameters:
    • aggregation (required) - Aggregation function: count, count_distinct, avg, sum, min, max, p50, p75, p90, p95, p99, rate
    • aggregateOn (optional) - Field to aggregate on (required for all except count and rate)
    • groupBy (optional) - Comma-separated fields to group by (e.g., 'service.name, severity_text')
    • filter (optional) - Filter expression using SigNoz search syntax
    • service (optional) - Shortcut filter for service name
    • severity (optional) - Shortcut filter for severity (DEBUG, INFO, WARN, ERROR, FATAL)
    • orderBy (optional) - Order expression and direction (e.g., 'count() desc')
    • limit (optional) - Maximum number of groups to return (default: 10)
    • timeRange (optional) - Time range like '30m', '1h', '6h', '24h' (default: '1h')
    • start / end (optional) - Start/end time in milliseconds

signoz_search_logs

Search logs with flexible filtering across all services. Supports query expressions, optional service/severity filters, and body text search.

  • Parameters:
    • query (optional) - Filter expression using SigNoz search syntax (e.g., "service.name = 'payment-svc' AND http.status_code >= 400")
    • service (optional) - Service name to filter by
    • severity (optional) - Severity filter (DEBUG, INFO, WARN, ERROR, FATAL)
    • searchText (optional) - Text to search for in log body (uses CONTAINS matching)
    • timeRange (optional) - Time range like '30m', '1h', '6h', '24h' (default: '1h')
    • start / end (optional) - Start/end time in milliseconds
    • limit (optional) - Maximum number of logs to return (default: 100)
    • offset (optional) - Offset for pagination (default: 0)

signoz_get_trace_field_values

Gets available field values for trace.

  • Parameters:
    • fieldName (required) - Field name to get values for (e.g., 'service.name', 'http.method')
    • searchText (optional) - Search text to filter values

signoz_get_logs_field_values

Gets available field values for log queries.

  • Parameters:
    • fieldName (required) - Field name to get values for (e.g., 'service.name')
    • searchText (optional) - Search text to filter values

signoz_get_metrics_field_values

Gets available field values for metric queries.

  • Parameters:
    • fieldName (required) - Field name to get values for
    • searchText (optional) - Search text to filter values

signoz_get_trace_available_fields

Gets available field names for trace queries.

  • Parameters:
    • searchText (optional) - Search text to filter available fields

signoz_get_logs_available_fields

Gets available field names for log queries.

  • Parameters:
    • searchText (optional) - Search text to filter available fields

signoz_get_metrics_available_fields

Gets available field names for metric queries.

  • Parameters:
    • searchText (optional) - Search text to filter available fields

signoz_search_traces_by_service

Searches traces for a specific service.

  • Parameters:
    • service (required) - Service name to search traces for
    • timeRange (optional) - Time range like '2h', '6h', '2d', '7d'
    • start (optional) - Start time in milliseconds (defaults to 6 hours ago)
    • end (optional) - End time in milliseconds (defaults to now)
    • operation (optional) - Operation name to filter by
    • error (optional) - Filter by error status (true/false)
    • minDuration (optional) - Minimum duration in nanoseconds
    • maxDuration (optional) - Maximum duration in nanoseconds
    • limit (optional) - Maximum number of traces to return (default: 100)

signoz_aggregate_traces

Aggregate traces to gets statistics like count, average, sum, min, max, or percentiles over spans, optionally grouped by fields.

  • Parameters:
    • aggregation (required) - Aggregation function: count, count_distinct, avg, sum, min, max, p50, p75, p90, p95, p99, rate
    • aggregateOn (optional) - Field to aggregate on (e.g., 'durationNano'). Required for all except count and rate
    • groupBy (optional) - Comma-separated fields to group by (e.g., 'service.name, name')
    • filter (optional) - Filter expression using SigNoz search syntax
    • service (optional) - Shortcut filter for service name
    • operation (optional) - Shortcut filter for span/operation name
    • error (optional) - Shortcut filter for error spans ('true' or 'false')
    • orderBy (optional) - Order expression and direction (e.g., 'avg(durationNano) desc')
    • limit (optional) - Maximum number of groups to return (default: 10)
    • timeRange (optional) - Time range like '30m', '1h', '6h', '24h' (default: '1h')
    • start / end (optional) - Start/end time in milliseconds

signoz_get_trace_details

Gets trace information including all spans and metadata.

  • Parameters:
    • traceId (required) - Trace ID to get details for
    • timeRange (optional) - Time range like '2h', '6h', '2d', '7d'
    • start (optional) - Start time in milliseconds (defaults to 6 hours ago)
    • end (optional) - End time in milliseconds (defaults to now)
    • includeSpans (optional) - Include detailed span information (true/false, default: true)

signoz_get_trace_error_analysis

Analyzes error patterns in traces.

  • Parameters:
    • timeRange (optional) - Time range like '2h', '6h', '2d', '7d'
    • start (optional) - Start time in milliseconds (defaults to 6 hours ago)
    • end (optional) - End time in milliseconds (defaults to now)
    • service (optional) - Service name to filter by
  • Returns: Traces with errors, useful for identifying patterns and affected services

signoz_get_trace_span_hierarchy

Gets trace span relationships and hierarchy.

  • Parameters:
    • traceId (required) - Trace ID to get span hierarchy for
    • timeRange (optional) - Time range like '2h', '6h', '2d', '7d'
    • start (optional) - Start time in milliseconds (defaults to 6 hours ago)
    • end (optional) - End time in milliseconds (defaults to now)

signoz_execute_builder_query

Executes a SigNoz Query Builder v5 query.

Time Format

Most tools support flexible time parameters:

Recommended: Time Ranges

Use the timeRange parameter with formats:

  • '30m' - Last 30 minutes
  • '2h' - Last 2 hours
  • '6h' - Last 6 hours
  • '2d' - Last 2 days
  • '7d' - Last 7 days

The timeRange parameter automatically calculates the time window from now backwards. If not specified, most tools default to the last 6 hours. You can also specify time in milliseconds and nanoseconds

Response Format

All tools return JSON responses that are optimized for LLM consumption:

  • List operations: Return summaries to avoid overwhelming responses
  • Detail operations: Return complete data when specific information is requested
  • Error handling: Structured error messages for debugging

🔧 Configuration & Deployment

Environment Variables

VariableDescriptionRequired
SIGNOZ_URLSigNoz instance URLYes
SIGNOZ_API_KEYSigNoz API key (get from Settings → Workspace Settings → API Key in SigNoz UI)Yes
LOG_LEVELLogging level: info(default), debug, warn, errorNo
TRANSPORT_MODEMCP transport mode: stdio(default) or httpNo
MCP_SERVER_PORTPort for HTTP transport modeYes only when TRANSPORT_MODE=http

Claude Desktop Extension Setup

🧱 Building the Claude Extension Bundle

Ensure Node.js is installed on your system. For details about the MCPB CLI, see Anthropic MCPB GitHub repository.

From the repository root, run:

make bundle

This command builds platform binaries (macOS and Windows), copies manifest and assets, installs the MCPB CLI (@anthropic-ai/mcpb), and packages everything into a Claude-compatible .mcpb bundle.

💻 Installing in Claude Desktop

  1. Open Claude Desktop → Settings → Developer → Edit Config -> Add bundle.mcpb

  2. Select the generated bundle:

    ./bundle/bundle.mcpb

  3. Provide your SigNoz configuration:

    • SIGNOZ_URL: URL of your SigNoz instance
    • SIGNOZ_API_KEY: API key from SigNoz UI → Settings → Workspace Settings → API Key
    • LOG_LEVEL: Optional (info, debug, or warn)

Restart Claude Desktop and it will then automatically start the SigNoz MCP Server and register its tools.

🤝 Contributing

We welcome contributions!

Development Setup

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests
  5. Submit a pull request

Code Style

  • Follow Go best practices
  • Use meaningful variable names
  • Add comments for complex logic
  • Ensure proper error handling

Made with ❤️ for the observability community