SigNoz MCP Server

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 Keys: Find specific metrics.
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: Gets log related to services, alerts, etc.
Traces: Search, 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.
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

Build or locate the binary path for signoz-mcp-server (for example: .../signoz-mcp-server/bin/signoz-mcp-server).
Goto Claude -> Settings -> Developer -> Local MCP Server click on edit config
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"
      }
    }
  }
}

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

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
Goto Claude -> Settings -> Developer -> Local MCP Server click on edit config
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

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

Add New Tools: Implement in internal/handler/tools/
Extend Client: Add methods to internal/client/client.go
Register Tools: Add to appropriate handler registration
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 24 hours"
"Get logs related to alert abc456"

Dashboard Management

"List all dashboards"
"Show me the Host Metrics dashboard details"

Service Analysis

"List all services from the last 24 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"

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"

Tool Reference

`list_metric_keys`

Lists all available metric keys from SigNoz.

`search_metric_keys`

Searches for metrics by text query.

Parameters: searchText (required) - Text to search for

`list_alerts`

Lists all active alerts from SigNoz.

`get_alert`

Gets details of a specific alert rule.

Parameters: ruleId (required) - Alert rule ID

`list_dashboards`

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

Returns: Simplified dashboard information for better LLM processing

`get_dashboard`

Gets complete dashboard configuration.

Parameters: uuid (required) - Dashboard UUID

`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 24 hours ago)
- end (optional) - End time in nanoseconds (defaults to now)

`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 24 hours ago)
- end (optional) - End time in nanoseconds (defaults to now)
- tags (optional) - JSON array of tags

`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 24 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')

`list_log_views`

Lists all saved log views from SigNoz.

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

`get_log_view`

Gets full details of a specific log view by ID.

Parameters: viewId (required) - Log view ID

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

`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 24 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)

`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 24 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)

`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

`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 24 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)

`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 24 hours ago)
- end (optional) - End time in milliseconds (defaults to now)
- includeSpans (optional) - Include detailed span information (true/false, default: true)

`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 24 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

`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 24 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

`signoz_query_helper`

Helper tool for building SigNoz queries.

Parameters:
- signal (optional) - Signal type: traces, logs, or metrics
- query_type (optional) - Type of help: fields, structure, examples, or all
Returns: Guidance on available fields, signal types, and query structure

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

Variable	Description	Required
`SIGNOZ_URL`	SigNoz instance URL	Yes
`SIGNOZ_API_KEY`	SigNoz API key (get from Settings → Workspace Settings → API Key in SigNoz UI)	Yes
`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

🤝 Contributing

We welcome contributions!

Development Setup

Fork the repository
Create a feature branch
Make your changes
Add tests
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

SigNoz

SigNoz MCP Server

🚀 Features

🏗️ Architecture

Core Components

🧰 Usage

Claude Desktop

Cursor

HTTP based self hosted mcp server

Claude Desktop

Cursor

🛠️ Development Guide

Prerequisites

Project Structure

Building from Source

Configuration

Running the Server

Development Workflow

📖 User Guide

For AI Assistants & LLMs

Metrics Exploration

Alert Monitoring

Dashboard Management

Service Analysis

Log Analysis

Trace Analysis

Tool Reference

list_metric_keys

search_metric_keys

list_alerts

get_alert

list_dashboards

get_dashboard

list_services

get_service_top_operations

get_alert_history

list_log_views

get_log_view

get_logs_for_alert

get_error_logs

search_logs_by_service

get_trace_field_values

search_traces_by_service

get_trace_details

get_trace_error_analysis

get_trace_span_hierarchy

signoz_execute_builder_query

signoz_query_helper

Time Format

Recommended: Time Ranges

Response Format

🔧 Configuration & Deployment

Environment Variables

🤝 Contributing

Development Setup

Code Style

MCP Now 重磅来袭，抢先一步体验

`list_metric_keys`

`search_metric_keys`

`list_alerts`

`get_alert`

`list_dashboards`

`get_dashboard`

`list_services`

`get_service_top_operations`

`get_alert_history`

`list_log_views`

`get_log_view`

`get_logs_for_alert`

`get_error_logs`

`search_logs_by_service`

`get_trace_field_values`

`search_traces_by_service`

`get_trace_details`

`get_trace_error_analysis`

`get_trace_span_hierarchy`

`signoz_execute_builder_query`

`signoz_query_helper`