SigNoz MCP Server

The SigNoz MCP Server implements the Model Context Protocol (MCP) — an open standard that lets AI assistants interact with external tools and data sources. It connects MCP-compatible clients (Claude Code/Desktop, Cursor, GitHub Copilot, OpenAI Codex, and others) to your SigNoz instance so you can query observability data in natural language.

Example use cases:

Ask your AI assistant "What alerts fired in the last hour?" and get structured results from SigNoz.
Debug issues by asking "Show me error logs for the payments service" without writing queries.
Explore traces, dashboards, and metrics through conversation.

📝 Note

The SigNoz MCP Server is functional but under active development. Expect breaking changes between releases. Early feedback is welcome — file issues on the GitHub repository.

Prerequisites

A running SigNoz instance — SigNoz Cloud or self-hosted
A SigNoz API key (see Get your API key below)
An MCP-compatible client: Claude Desktop, Cursor, GitHub Copilot, Claude Code, or OpenAI Codex
To build from source: Go 1.25+ and make, or Docker

Get your API key

Log in to your SigNoz instance.
Go to Settings → API Keys.
Click Create API Key and copy the generated key.

⚠️ Warning

Keep your API key secure. Never commit it to version control — use environment variables or a secrets manager.

Installation

The SigNoz MCP Server is open source: github.com/SigNoz/signoz-mcp-server

Clone the repository and build the binary:

git clone https://github.com/SigNoz/signoz-mcp-server.git
cd signoz-mcp-server
go build -o bin/signoz-mcp-server ./cmd/server/

The binary is created at bin/signoz-mcp-server. Note the absolute path — you will need it when configuring your MCP client.

✅ Info

The repository also includes a Makefile. Running make build works but requires goimports to be installed and on your PATH. The go build command above has no extra dependencies beyond Go itself.

Clone the repository:

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

Create a .env file in the project root with your SigNoz configuration:

SIGNOZ_URL=<your-signoz-url>
SIGNOZ_API_KEY=<your-api-key>
LOG_LEVEL=info

<your-signoz-url>: Your SigNoz instance URL (e.g., https://your-instance.signoz.cloud)
<your-api-key>: The API key from Get your API key

Start the server:

docker-compose up -d

The server starts in HTTP mode on port 8000 by default. You can override the port by adding MCP_SERVER_PORT=<port> to your .env file.

✅ Info

The Docker setup always runs in HTTP transport mode. Use the HTTP tab in the Setup section below to configure your MCP client.

Setup

The MCP server supports two transport modes: Stdio (local binary, launched by the client) and HTTP (standalone server the client connects to over the network). Choose your AI client below and follow the instructions for your preferred transport.

Build or download the signoz-mcp-server binary (see Installation).
In Claude Desktop, go to Settings → Developer → Edit Config.
Add the following to claude_desktop_config.json:

{
  "mcpServers": {
    "signoz": {
      "command": "<path-to-binary>/signoz-mcp-server",
      "args": [],
      "env": {
        "SIGNOZ_URL": "<your-signoz-url>",
        "SIGNOZ_API_KEY": "<your-api-key>",
        "LOG_LEVEL": "info"
      }
    }
  }
}

<path-to-binary>: Absolute path to the signoz-mcp-server binary (e.g., /Users/you/signoz-mcp-server/bin/signoz-mcp-server)
<your-signoz-url>: Your SigNoz instance URL (e.g., https://your-instance.signoz.cloud)
<your-api-key>: The API key from Get your API key

Restart Claude Desktop. The signoz server should appear in the developer console with its tools available.

Start the MCP server in HTTP mode:

SIGNOZ_URL=<your-signoz-url> \
SIGNOZ_API_KEY=<your-api-key> \
TRANSPORT_MODE=http \
MCP_SERVER_PORT=8000 \
LOG_LEVEL=info \
./signoz-mcp-server

<your-signoz-url>: Your SigNoz instance URL
<your-api-key>: The API key from Get your API key

Or use docker-compose (see the repository for examples).

In Claude Desktop, go to Settings → Developer → Edit Config.
Add the following to claude_desktop_config.json:

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

✅ Info

If you omit SIGNOZ_API_KEY when starting the server, you can pass it via the client's Authorization header instead:

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

This is useful for hosted MCP servers or multi-tenant setups where each client authenticates independently.

Restart Claude Desktop. The signoz server should appear in the developer console with its tools available.

You can configure this via the GUI or a project config file:

GUI: Open Cursor → Settings → Cursor Settings → Tools & Integrations → + New MCP Server
Config file: Create .cursor/mcp.json in your project root

Use the following JSON for either method:

{
  "mcpServers": {
    "signoz": {
      "command": "<path-to-binary>/signoz-mcp-server",
      "args": [],
      "env": {
        "SIGNOZ_URL": "<your-signoz-url>",
        "SIGNOZ_API_KEY": "<your-api-key>",
        "LOG_LEVEL": "info"
      }
    }
  }
}

<path-to-binary>: Absolute path to the signoz-mcp-server binary
<your-signoz-url>: Your SigNoz instance URL
<your-api-key>: The API key from Get your API key

Restart Cursor to activate the SigNoz tools.

✅ Info

The GUI method (Cursor → Settings → Cursor Settings → Tools & Integrations) configures the server globally across all your projects. The .cursor/mcp.json file is project-specific — commit it to share with your team.

Start the MCP server in HTTP mode:

SIGNOZ_URL=<your-signoz-url> \
SIGNOZ_API_KEY=<your-api-key> \
TRANSPORT_MODE=http \
MCP_SERVER_PORT=8000 \
LOG_LEVEL=info \
./signoz-mcp-server

Or use docker-compose (see the repository for examples).

<your-signoz-url>: Your SigNoz instance URL
<your-api-key>: The API key from Get your API key

Configure Cursor:
- GUI: Open Cursor → Settings → Cursor Settings → Tools & Integrations → + New MCP Server
- Config file: Create .cursor/mcp.json in your project root

Use the following JSON for either method:

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

✅ Info

If you omit SIGNOZ_API_KEY when starting the server, pass it via the Authorization header instead:

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

Restart Cursor to activate the SigNoz tools.

GitHub Copilot supports both global (across all VS Code workspaces) and project-level (specific to one repository) configurations.

Build or download the signoz-mcp-server binary (see Installation).
In VS Code, open the Command Palette (Cmd+Shift+P on Mac, Ctrl+Shift+P on Windows/Linux) and run MCP: Open User Configuration.
Add the SigNoz server to the servers object:

{
  "servers": {
    "signoz": {
      "type": "stdio",
      "command": "<path-to-binary>/signoz-mcp-server",
      "args": [],
      "env": {
        "SIGNOZ_URL": "<your-signoz-url>",
        "SIGNOZ_API_KEY": "<your-api-key>",
        "LOG_LEVEL": "info"
      }
    }
  }
}

<path-to-binary>: Absolute path to the signoz-mcp-server binary
<your-signoz-url>: Your SigNoz instance URL (e.g., https://your-instance.signoz.cloud)
<your-api-key>: The API key from Get your API key

Open Copilot Chat in Agent mode. When prompted, confirm that you trust the SigNoz MCP server.

Add the configuration directly to your codebase to share the MCP setup with your team.

Build or download the signoz-mcp-server binary (see Installation).
Create a .vscode/mcp.json file in your project root:

{
  "servers": {
    "signoz": {
      "type": "stdio",
      "command": "<path-to-binary>/signoz-mcp-server",
      "args": [],
      "env": {
        "SIGNOZ_URL": "<your-signoz-url>",
        "SIGNOZ_API_KEY": "<your-api-key>",
        "LOG_LEVEL": "info"
      }
    }
  }
}

<path-to-binary>: Absolute path to the signoz-mcp-server binary
<your-signoz-url>: Your SigNoz instance URL (e.g., https://your-instance.signoz.cloud)
<your-api-key>: The API key from Get your API key

Open Copilot Chat in Agent mode and confirm you trust the server.

Claude Code is an agentic CLI tool. You can configure plugins globally or just for your current project.

Run this command anywhere to make the SigNoz tools available across all your Claude Code projects:

claude mcp add --scope user signoz "<path-to-binary>/signoz-mcp-server" -e SIGNOZ_URL="<your-signoz-url>" -e SIGNOZ_API_KEY="<your-api-key>" -e LOG_LEVEL=info

<path-to-binary>: Absolute path to the signoz-mcp-server binary you built earlier
<your-signoz-url>: Your SigNoz instance URL (e.g., https://your-instance.signoz.cloud)
<your-api-key>: The API key from Get your API key

To add the MCP tools only to the current folder (which updates your project's .mcp.json), add the --scope project flag:

cd your-project-folder
claude mcp add --scope project signoz "<path-to-binary>/signoz-mcp-server" -e SIGNOZ_URL="<your-signoz-url>" -e SIGNOZ_API_KEY="<your-api-key>" -e LOG_LEVEL=info

<path-to-binary>: Absolute path to the signoz-mcp-server binary you built earlier
<your-signoz-url>: Your SigNoz instance URL (e.g., https://your-instance.signoz.cloud)
<your-api-key>: The API key from Get your API key

If you prefer to run the SigNoz MCP server in HTTP mode (e.g. running via Docker), use the --transport http flag along with your preferred scope (--scope user or --scope project):

claude mcp add --scope user --transport http signoz http://localhost:8000/mcp

✅ Info

To remove the server later, use claude mcp remove signoz (add --scope project if you installed it locally). You can view all active servers with claude mcp list.

Codex supports both CLI command-style addition and configuration file editing via config.toml.

Run this command structure to add the SigNoz MCP server using the Codex CLI:

codex mcp add signoz --env SIGNOZ_URL="<your-signoz-url>" --env SIGNOZ_API_KEY="<your-api-key>" --env LOG_LEVEL=info -- "<path-to-binary>/signoz-mcp-server"

<path-to-binary>: Absolute path to the signoz-mcp-server binary you built earlier
<your-signoz-url>: Your SigNoz instance URL (e.g., https://your-instance.signoz.cloud)
<your-api-key>: The API key from Get your API key

Open your Codex configuration file. For global setup, edit ~/.codex/config.toml. For project-specific setup, edit .codex/config.toml in your project root. (You can also open this via the IDE extension using MCP settings > Open config.toml).
Add the SigNoz server block:

[mcp_servers.signoz]
command = "<path-to-binary>/signoz-mcp-server"
args = []

[mcp_servers.signoz.env]
SIGNOZ_URL = "<your-signoz-url>"
SIGNOZ_API_KEY = "<your-api-key>"
LOG_LEVEL = "info"

<path-to-binary>: Absolute path to the signoz-mcp-server binary you built earlier
<your-signoz-url>: Your SigNoz instance URL (e.g., https://your-instance.signoz.cloud)
<your-api-key>: The API key from Get your API key

Validate

After setting up your MCP client, confirm the server is working:

Open your AI assistant (Claude Desktop, Cursor, Copilot, Codex, or run claude in your terminal).
Ask: "List all alerts" or "Show me all available services".
The assistant should return structured results from your SigNoz instance. If it does, the MCP server is connected and working correctly.

Configuration Reference

All configuration is done via environment variables:

Variable	Description	Default
`SIGNOZ_URL`	URL of your SigNoz instance	(required)
`SIGNOZ_API_KEY`	API key for authenticating with SigNoz	(required unless passed via client header)
`TRANSPORT_MODE`	Transport protocol: `stdio` or `http`	`stdio`
`MCP_SERVER_PORT`	Port for the HTTP server (only used when `TRANSPORT_MODE=http`)	`8000`
`LOG_LEVEL`	Logging verbosity: `debug`, `info`, `warn`, `error`	`info`

Available Tools

The MCP server exposes the following tools to your AI assistant, grouped by domain:

Metrics

Tool	Description
List Metric Keys	Retrieve all available metric keys from SigNoz
Search Metric Keys	Find specific metrics containing given text
Get Metrics Field Values	Gets available field values for metric queries
Get Metrics Available Fields	Gets available field names for metric queries

Alerts

Tool	Description
List Alerts	Get all active alerts with detailed status
Get Alert Details	Retrieve comprehensive information about a specific alert rule
Get Alert History	Timeline of alert state changes for a specific rule
Get Logs for Alert	Fetch logs related to a specific alert automatically

Logs

Tool	Description
Get Error Logs	Retrieve logs with ERROR or FATAL severity
Search Logs by Service	Search and filter logs for a specific service
Search Logs	Search logs with flexible filtering across all services
Aggregate Logs	Aggregate logs to provide statistics optionally grouped by fields
List Log Views	Get all saved log views
Get Log View	Retrieve a saved log view's complete configuration
Get Logs Field Values	Gets available field values for log queries
Get Logs Available Fields	Gets available field names for log queries

Dashboards

Tool	Description
List Dashboards	Get dashboard summaries (name, UUID, description, tags)
Get Dashboard	Retrieve complete dashboard configuration with panels and queries
Create Dashboard	Create a new monitoring dashboard from a JSON definition
Update Dashboard	Update an existing dashboard using its UUID and full JSON

Services and Traces

Tool	Description
List Services	Discover all services within a specified time range
Service Top Operations	Analyze performance metrics for a specific service
Search Traces by Service	Search traces with filters (errors, duration, operation)
Aggregate Traces	Aggregate traces to get statistics over spans
Get Trace Details	Get comprehensive trace information with all spans and metadata
Get Trace Error Analysis	Analyze error patterns across traces
Get Trace Span Hierarchy	View span relationships and hierarchy within a trace
Get Trace Field Values	Gets available field values for trace queries
Get Trace Available Fields	Gets available field names for trace queries

Query

Tool	Description
Query Builder	Generate and execute complex queries against SigNoz data

Troubleshooting

Tools not appearing in the AI client

Verify the binary path in your config is correct and the file is executable.
Check that SIGNOZ_URL and SIGNOZ_API_KEY are set correctly.
Restart the AI client after modifying the config.
Set LOG_LEVEL=debug to see detailed server logs and identify connection issues.

Authentication errors

Confirm your API key is valid and has not expired.
If using HTTP mode with the Authorization header, ensure the format is Bearer <your-api-key>.
If using Stdio mode, verify the SIGNOZ_API_KEY environment variable is set in the config JSON.

Server not starting (HTTP mode)

Ensure the port (default 8000) is not already in use.
Check that TRANSPORT_MODE=http is set.
Review server logs for startup errors.

SigNoz MCP Server

Prerequisites

Get your API key

Installation

Setup

Validate

Configuration Reference

Available Tools

Metrics

Alerts

Logs

Dashboards

Services and Traces

Query

Troubleshooting

Tools not appearing in the AI client

Authentication errors

Server not starting (HTTP mode)

Was this page helpful?

Is this page helpful?