Signoz MCP Server

🚀 Signoz MCP Server

The MCP server offers various tools to interact with Signoz, enabling users to manage dashboards, fetch metrics, execute queries, and more.

🚀 Quick Start

Watch the working demo on Cursor 📽️ https://youtube.com/shorts/jxjmGyXXz7A

✨ Features

The following tools are available via the MCP server:

• test_connection: Verify connectivity to your Signoz instance and configuration.
• fetch_dashboards: List all available dashboards from Signoz.
• fetch_dashboard_details: Retrieve detailed information about a specific dashboard by its ID. This information contains the metadata of the dashboard, not the live panel data.
• fetch_dashboard_data: Fetch all panel data for a given dashboard by name and time range.
• fetch_apm_metrics: Retrieve standard APM metrics (request rate, error rate, latency, apdex, etc.) for a given service and time range.
• fetch_services: Fetch all instrumented services from Signoz with optional time range filtering.
• execute_clickhouse_query: Execute custom Clickhouse SQL queries via the Signoz API with time range support.
• execute_builder_query: Execute Signoz builder queries for custom metrics and aggregations with time range support.
• fetch_traces_or_logs: Fetch traces or logs from SigNoz using ClickHouse SQL. Specify data_type ('traces' or 'logs'), time range, service name, and limit. Returns tabular results for traces or logs.

📦 Installation

1. Get Your Signoz API Endpoint & (Optional) API Key

1. Ensure you have a running Signoz instance (self - hosted or cloud).
2. (Optional) If your Signoz instance requires an API key for the health endpoint, generate or obtain it from your Signoz UI.

2. Installation & Running Options

2A. Install & Run with uv (Recommended for Local Development)

2A.1. Install dependencies with uv

uv venv .venv
source .venv/bin/activate
uv sync

2A.2. Run the server with uv

uv run -m src.signoz_mcp_server.mcp_server

• You can also use uv to run any other entrypoint scripts as needed.
• Make sure your config.yaml is in the same directory as mcp_server.py or set the required environment variables (see Configuration section).

2B. Run with Docker Compose (Recommended for Production/Containerized Environments)

1. Edit src/signoz_mcp_server/config.yaml with your Signoz details (host, API key if needed).
2. Start the server:

docker-compose up -d

• The server will run in HTTP (SSE) mode on port 8000 by default.
• You can override configuration with environment variables (see below).

💻 Usage Examples

Configuration

The server loads configuration in the following order of precedence:

1. Environment Variables (recommended for Docker/CI):
   • SIGNOZ_HOST: Signoz instance URL (e.g. https://your-signoz-instance.com)
   • SIGNOZ_API_KEY: Signoz API key (optional)
   • SIGNOZ_SSL_VERIFY: true or false (default: true)
   • MCP_SERVER_PORT: Port to run the server on (default: 8000)
   • MCP_SERVER_DEBUG: true or false (default: true)
2. YAML file fallback (config.yaml):

signoz:
  host: "https://your-signoz-instance.com"
  api_key: "your-signoz-api-key-here" # Optional
  ssl_verify: "true"
server:
  port: 8000
  debug: true

Integration with AI Assistants (e.g., Claude Desktop, Cursor)

4A. Using Local Setup (with uv)

Before running the server locally, install dependencies and run with uv:

uv sync

Then add to your client configuration (e.g., claude-desktop.json):

{
  "mcpServers": {
    "signoz": {
      "command": "/path/to/uv",
      "args": [
        "--directory",
        "/full/path/to/signoz-mcp-server",
        "run",
        "src/signoz_mcp_server/mcp_server.py"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "SIGNOZ_HOST": "https://your-signoz-instance.com",
        "SIGNOZ_API_KEY": "your-signoz-api-key-here",
        "SIGNOZ_SSL_VERIFY": "true"
      }
    }
  }
}

• The path to uv can be found by running which uv on MacOS/Linux or where uv on Windows.
• Ensure your config.yaml is in the same directory as mcp_server.py or update the path accordingly.

4B. Using Docker Compose or Docker (with environment variables, mcp - grafana style)

{
  "mcpServers": {
    "signoz": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "SIGNOZ_HOST",
        "-e",
        "SIGNOZ_API_KEY",
        "-e",
        "SIGNOZ_SSL_VERIFY",
        "ddroid/signoz-mcp-server",
        "-t",
        "stdio"
      ],
      "env": {
        "SIGNOZ_HOST": "https://your-signoz-instance.com",
        "SIGNOZ_API_KEY": "your-signoz-api-key-here",
        "SIGNOZ_SSL_VERIFY": "true"
      }
    }
  }
}

• The -t stdio argument is supported for compatibility with Docker MCP clients (forces stdio handshake mode).
• Adjust the volume path or environment variables as needed for your deployment.

4C. Connecting to an Already Running MCP Server (HTTP/SSE)

If you have an MCP server already running (e.g., on a remote host, cloud VM, or Kubernetes), you can connect your AI assistant or tool directly to its HTTP endpoint.

Example: Claude Desktop or Similar Tool

{
  "mcpServers": {
    "signoz": {
      "url": "http://your-server-host:8000/mcp"
    }
  }
}

• Replace your-server-host with the actual host where your MCP server is running.
• For local setup, use localhost as the server host (i.e., http://localhost:8000/mcp).
• Use http for local or unsecured deployments, and https for production or secured deployments.
• Make sure the server is accessible from your client machine (check firewall, security group, etc.).

Example: MCP Config YAML

mcp:
  endpoint: "http://your-server-host:8000/mcp"
  protocolVersion: "2025-06-18"

• Replace your-server-host with the actual host where your MCP server is running.
• For local setup, use localhost as the server host (i.e., http://localhost:8000/mcp).
• Use http or https in the URL schema depending on how you've deployed the MCP server.
• No need to specify command or args—just point to the HTTP endpoint.
• This works for any tool or assistant that supports MCP over HTTP.
• The server must be running in HTTP (SSE) mode (the default for this implementation).

Health Check

curl http://localhost:8000/health

The server runs on port 8000 by default.

📚 Documentation

Miscellaneous

1. Need help anywhere? Join our slack community and message on #mcp channel.
2. Want to try without setting up? Follow this doc for a quickstart on DrDroid cloud platform.