SigNoz MCP Server

A Model Context Protocol (MCP) server that provides seamless access to SigNoz observability data through AI assistants and LLMs. Query metrics, traces, logs, alerts, dashboards, and services using natural language.

📖 Full Documentation

Table of Contents

• Connect to SigNoz Cloud
• Self-Hosted Installation
• Connect to Self-Hosted SigNoz
• What Can You Do With It?
• Available Tools
• Environment Variables
• Claude Desktop Extension
• Architecture
• Contributing

Connect to SigNoz Cloud

Connect your AI tool to SigNoz Cloud's hosted MCP server. No installation is required; just add the hosted MCP URL and authenticate.

https://mcp.<region>.signoz.cloud/mcp

Make sure you select the correct region that matches your SigNoz Cloud account. Using the wrong region will result in authentication failures.

Find your region under Settings → Ingestion in SigNoz, or see the SigNoz Cloud region reference.

One-Click Install Links

GitHub does not reliably make custom-protocol links like cursor:// and vscode: clickable in README rendering.

Use the documentation page for one-click install buttons:

• Open one-click install links for Cursor
• Open one-click install links for VS Code

If you prefer, use the manual configuration examples below in this README.

Cursor

Manual Configuration

Add this configuration to .cursor/mcp.json:

{
  "mcpServers": {
    "signoz": {
      "url": "https://mcp.<region>.signoz.cloud/mcp"
    }
  }
}

Need help? See the Cursor MCP docs.

VS Code / GitHub Copilot

Manual Configuration

Add this configuration to .vscode/mcp.json:

{
  "servers": {
    "signoz": {
      "type": "http",
      "url": "https://mcp.<region>.signoz.cloud/mcp"
    }
  }
}

Need help? See the VS Code MCP docs.

Claude Desktop

Add SigNoz Cloud as a custom connector in Claude Desktop:

1. Open Claude Desktop.
2. Go to Settings → Developer (or Features, depending on your version).
3. Click Add Custom Connector or Add Remote MCP Server.
4. Enter your SigNoz MCP URL: https://mcp.<region>.signoz.cloud/mcp

When prompted, complete the authentication flow.

Claude Code

Run this command to add the hosted SigNoz MCP server:

claude mcp add --scope user --transport http signoz https://mcp.<region>.signoz.cloud/mcp

After configuring the MCP server, authenticate in a terminal:

claude /mcp

Select the signoz server and complete the authentication flow.

OpenAI Codex

Run this command to add the hosted SigNoz MCP server:

codex mcp add signoz --url https://mcp.<region>.signoz.cloud/mcp

Or add this configuration to config.toml:

[mcp_servers.signoz]
url = "https://mcp.<region>.signoz.cloud/mcp"

After adding the server, authenticate:

codex mcp login signoz

Then run /mcp inside Codex to verify the connection.

SigNoz Cloud Authentication

When you add the hosted MCP URL to your client, the client initiates an authentication flow. You will be prompted to enter:

1. Your SigNoz instance URL (for example, https://your-instance.signoz.cloud)
2. Your API key

Create an API key in Settings → API Keys in SigNoz. Only Admin users can create API keys.

Self-Hosted Installation

Download Binary (Recommended)

Download the latest binary from GitHub Releases:

# macOS (Apple Silicon)
curl -L https://github.com/SigNoz/signoz-mcp-server/releases/latest/download/signoz-mcp-server_darwin_arm64.tar.gz | tar xz

# macOS (Intel)
curl -L https://github.com/SigNoz/signoz-mcp-server/releases/latest/download/signoz-mcp-server_darwin_amd64.tar.gz | tar xz

# Linux (amd64)
curl -L https://github.com/SigNoz/signoz-mcp-server/releases/latest/download/signoz-mcp-server_linux_amd64.tar.gz | tar xz

This extracts a signoz-mcp-server binary in the current directory. Move it somewhere on your PATH or note the absolute path for the config below.

Go Install

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

The binary is installed as server to $GOPATH/bin/ (default: $HOME/go/bin/server). You may want to rename it:

mv "$(go env GOPATH)/bin/server" "$(go env GOPATH)/bin/signoz-mcp-server"

Docker

Docker images are available on Docker Hub:

docker pull signoz/signoz-mcp-server:latest

Run in HTTP mode:

docker run -p 8000:8000 \
  -e TRANSPORT_MODE=http \
  -e MCP_SERVER_PORT=8000 \
  -e SIGNOZ_URL=https://your-signoz-instance.com \
  -e SIGNOZ_API_KEY=your-api-key \
  signoz/signoz-mcp-server:latest

Use a specific version tag (e.g. v0.1.0) instead of latest for pinned deployments.

Build from Source

git clone https://github.com/SigNoz/signoz-mcp-server.git
cd signoz-mcp-server
make build

The binary is at ./bin/signoz-mcp-server.

Connect to Self-Hosted SigNoz

Prerequisites

• A running SigNoz instance
• A SigNoz API key (Settings → API Keys in the SigNoz UI)
• The signoz-mcp-server binary (see Self-Hosted Installation)

Stdio Mode (Claude Desktop / Cursor / Any MCP Client)

Add this to your MCP client config (claude_desktop_config.json, .cursor/mcp.json, etc.). Replace the command path with the absolute path to your signoz-mcp-server binary:

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

HTTP Mode

With OAuth (Multi-Tenant / Cloud)

Start the server:

TRANSPORT_MODE=http \
MCP_SERVER_PORT=8000 \
OAUTH_ENABLED=true \
OAUTH_TOKEN_SECRET=$(openssl rand -base64 32) \
OAUTH_ISSUER_URL=https://your-public-mcp-url.com \
./signoz-mcp-server

Client config — just the URL, no keys needed:

{
    "mcpServers": {
        "signoz": {
            "url": "https://your-public-mcp-url.com/mcp"
        }
    }
}

The client discovers OAuth endpoints automatically, opens a browser for credentials, and handles token exchange.

Without OAuth (Simple Setup)

The API key and SigNoz URL only need to be provided in one place — either on the server or on the client.

Option A — Credentials on the server (simpler client config):

SIGNOZ_URL=https://your-signoz-instance.com \
SIGNOZ_API_KEY=your-api-key \
TRANSPORT_MODE=http \
MCP_SERVER_PORT=8000 \
./signoz-mcp-server

{
    "mcpServers": {
        "signoz": {
            "url": "http://localhost:8000/mcp"
        }
    }
}

Option B — API key on the client (server holds the URL, client sends the key):

SIGNOZ_URL=https://your-signoz-instance.com \
TRANSPORT_MODE=http \
MCP_SERVER_PORT=8000 \
./signoz-mcp-server

{
    "mcpServers": {
        "signoz": {
            "url": "http://localhost:8000/mcp",
            "headers": {
                "SIGNOZ-API-KEY": "your-api-key-here"
            }
        }
    }
}

What Can You Do With It?

"Show me all available metrics"
"What's the p99 latency for http_request_duration_seconds?"
"List all active alerts"
"Show me error logs for the paymentservice from the last hour"
"How many errors per service in the last hour?"
"Search traces for the checkout service from the last hour"
"Get details for trace ID abc123"
"Create a dashboard with CPU and memory widgets"

Available Tools

Tool	Description
signoz_list_metrics	Search and list available metrics
signoz_query_metrics	Query metrics with smart aggregation defaults
signoz_get_field_keys	Discover available field keys for metrics, traces, or logs
signoz_get_field_values	Get possible values for a field key
signoz_list_alerts	List all active alerts
signoz_get_alert	Get details of a specific alert rule
signoz_get_alert_history	Get alert history timeline for a rule
signoz_list_dashboards	List all dashboards with summaries
signoz_get_dashboard	Get full dashboard configuration
signoz_create_dashboard	Create a new dashboard
signoz_update_dashboard	Update an existing dashboard
signoz_list_services	List services within a time range
signoz_get_service_top_operations	Get top operations for a service
signoz_list_log_views	List all saved log views
signoz_get_log_view	Get details of a saved log view
signoz_aggregate_logs	Aggregate logs (count, avg, p99, etc.) with grouping
signoz_search_logs	Search logs with flexible filtering
signoz_aggregate_traces	Aggregate trace statistics with grouping
signoz_search_traces	Search traces with flexible filtering
signoz_get_trace_details	Get full trace with all spans
signoz_execute_builder_query	Execute a raw Query Builder v5 query

For detailed usage and examples, see the full documentation.

Parameter Reference

signoz_list_metrics

Search and list available metrics from SigNoz. Supports filtering by name substring, time range, and source.

• Parameters:
  • searchText (optional) - Filter metrics by name substring (e.g., 'cpu', 'memory')
  • limit (optional) - Maximum number of metrics to return (default: 50)
  • start (optional) - Start time in unix milliseconds
  • end (optional) - End time in unix milliseconds
  • source (optional) - Filter by source

signoz_query_metrics

Query metrics with smart aggregation defaults and validation. Automatically applies the right timeAggregation and spaceAggregation based on metric type (gauge, counter, histogram). Auto-fetches metric metadata if not provided.

• Parameters:
  • metricName (required) - Metric name to query
  • metricType (optional) - gauge, sum, histogram, exponential_histogram (auto-fetched if absent)
  • isMonotonic (optional) - true/false (auto-fetched if absent)
  • temporality (optional) - cumulative, delta, unspecified (auto-fetched if absent)
  • timeAggregation (optional) - Aggregation over time (auto-defaulted by type)
  • spaceAggregation (optional) - Aggregation across dimensions (auto-defaulted by type)
  • groupBy (optional) - Comma-separated field names
  • filter (optional) - Filter expression
  • timeRange (optional) - Relative range: 30m, 1h, 6h, 24h, 7d (default: 1h)
  • start/end (optional) - Unix ms timestamps (override timeRange)
  • stepInterval (optional) - Step in seconds (auto-calculated if omitted)
  • requestType (optional) - time_series (default) or scalar
  • reduceTo (optional) - For scalar: sum, count, avg, min, max, last, median
  • formula (optional) - Expression over named queries (e.g., "A / B * 100")
  • formulaQueries (optional) - JSON array of additional named metric queries for formula

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).

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

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

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.

signoz_get_log_view

Gets full details of a specific log view by ID.

• Parameters: viewId (required) - Log view ID

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 with count, average, sum, min, max, or percentiles, 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 (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.

• 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_field_keys

Get available field keys for a given signal (metrics, traces, or logs).

• Parameters:
  • signal (required) - Signal type: metrics, traces, or logs
  • searchText (optional) - Filter field keys by name substring
  • metricName (optional) - Filter by metric name (relevant for metrics signal)
  • fieldContext (optional) - Filter by field context (e.g., resource, span)
  • fieldDataType (optional) - Filter by data type (e.g., string, int64)
  • source (optional) - Filter by source

signoz_get_field_values

Get possible values for a specific field key for a given signal.

• Parameters:
  • signal (required) - Signal type: metrics, traces, or logs
  • name (required) - Field key name to get values for (e.g., service.name, http.method)
  • searchText (optional) - Filter values by substring
  • metricName (optional) - Filter by metric name (relevant for metrics signal)
  • source (optional) - Filter by source

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 trace 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

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.

• Parameters: query (required) - Complete SigNoz Query Builder v5 JSON object
• Documentation: See SigNoz Query Builder v5 docs

Environment Variables

Variable	Description	Required
SIGNOZ_URL	SigNoz instance URL	Yes (stdio); Optional (http with OAuth)
SIGNOZ_API_KEY	SigNoz API key (get from Settings → API Keys in the SigNoz UI)	Yes (stdio); Optional (http with OAuth)
LOG_LEVEL	Logging level: info(default), debug, warn, error	No
TRANSPORT_MODE	MCP transport mode: stdio(default) or http	No
MCP_SERVER_PORT	Port for HTTP transport mode	Yes only when TRANSPORT_MODE=http
OAUTH_ENABLED	Enable OAuth 2.1 authentication flow (true/false)	No (default: false)
OAUTH_TOKEN_SECRET	Encryption key for OAuth tokens (min 32 bytes, e.g. openssl rand -base64 32)	Yes when OAUTH_ENABLED=true
OAUTH_ISSUER_URL	Public URL of this MCP server (used in OAuth metadata discovery)	Yes when OAUTH_ENABLED=true
OAUTH_ACCESS_TOKEN_TTL_MINUTES	Access token lifetime in minutes (default: 60)	No
OAUTH_REFRESH_TOKEN_TTL_MINUTES	Refresh token lifetime in minutes (default: 1440 / 24h)	No
OAUTH_AUTH_CODE_TTL_SECONDS	Authorization code lifetime in seconds (default: 600 / 10min)	No

Claude Desktop Extension

Building the Bundle

Requires Node.js. See Anthropic MCPB for details.

make bundle

Installing

1. Open Claude Desktop → Settings → Developer → Edit Config → Add bundle.mcpb
2. Select ./bundle/bundle.mcpb
3. Enter your SIGNOZ_URL, SIGNOZ_API_KEY, and optionally LOG_LEVEL
4. Restart Claude Desktop

Architecture

For a detailed overview of request flow, component interactions, and design decisions, see docs/architecture.md.

Contributing

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

Made with ❤️ for the observability community