SigNoz Cloud - This page is relevant for SigNoz Cloud editions.
Self-Host - This page is relevant for self-hosted SigNoz editions.

SigNoz MCP Server

MCP (Model Context Protocol) is an open-source standard for connecting AI applications to external systems.

Signoz MCP Server lets AI assistance and LLMs connect to Signoz observability data. Integration of signoz-mcp-server with LLMs and AI assistance like Cursor or Claude enables you to query in natural language and get more precise and structured information.

Working

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

📌 Note: Signoz MCP Server is ready for use but under heavy development and its expected to see changes. Early feedback is appreciated.

Current state of signoz-mcp-server provides tools as mentioned below.

  • 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: Timeline of alert history for specific rules
  • Get Logs for Alert: Logs related to specific alerts automatically
  • Get Error Logs: Logs with ERROR or FATAL severity
  • Search Logs by Service: Search logs for specific services with filters
  • List Log Views: Get all saved log views
  • Get Log View: Retrieve complete log view configuration
  • 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
  • Get Trace Field Values: Available field values for trace queries
  • Search Traces by Service: Search traces with filters (errors, duration, operation)
  • Get Trace Details: Comprehensive trace information with all spans and metadata
  • Get Trace Error Analysis: Analyze error patterns in traces
  • Get Trace Span Hierarchy: Trace span relationships and hierarchy

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

Installation

The SigNoz MCP Server is available as open-source software on GitHub: https://github.com/SigNoz/signoz-mcp-server

Building from Source:

  1. Clone the repository:
git clone https://github.com/SigNoz/signoz-mcp-server.git
cd signoz-mcp-server
  1. Build the binary:
make build

The binary will be created at bin/signoz-mcp-server.

Using Docker:

You can also run the MCP server using Docker Compose. See the repository for docker-compose configuration examples.

Integrations

In current state signoz-mcp-server can be integrated with Stdio or http mode, tested with Cursor and Claude.

Claude Desktop

Stdio based

  1. Build or locate the binary path for signoz-mcp-server (for example: .../signoz-mcp-server/bin/signoz-mcp-server).
  2. Go to 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.

📌 Note: Replace the command path with your actual binary location.

HTTP based

HTTP mode supports two authentication methods:

Method 1: Environment Variable

  1. Build and run signoz-mcp-server with API key in environment:
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.

  1. Go to Claude -> Settings -> Developer -> Local MCP Server click on edit config
  2. Edit claude_desktop_config.json:
{
  "mcpServers": {
    "signoz": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Method 2: Authorization Header

  1. Build and run signoz-mcp-server without API key in environment:
SIGNOZ_URL=signoz_url TRANSPORT_MODE=http MCP_SERVER_PORT=8000 LOG_LEVEL=log_level ./signoz-mcp-server
  1. Go to Claude -> Settings -> Developer -> Local MCP Server click on edit config
  2. Edit claude_desktop_config.json with API key in Authorization header:
{
  "mcpServers": {
    "signoz": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer your-signoz-api-key-here"
      }
    }
  }
}

This method allows application-level access control and is ideal for hosted MCP servers or multi-tenant scenarios.

  1. Restart Claude Desktop. You should see the signoz server load in the developer console and its tools become available.

Cursor

Stdio based

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

HTTP mode supports two authentication methods:

Method 1: Environment Variable

Build and run signoz-mcp-server with API key in environment:

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 this JSON structure:

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

Method 2: Authorization Header

Build and run signoz-mcp-server without API key in environment:

SIGNOZ_URL=signoz_url TRANSPORT_MODE=http MCP_SERVER_PORT=8000 LOG_LEVEL=log_level ./signoz-mcp-server

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 this JSON structure with Authorization header:

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

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

Last updated: September 26, 2025

Edit on GitHub

Was this page helpful?