SigNoz MCP Server provides a set of MCP-compatible tools to query and manage your SigNoz observability data through natural language AI assistants. It exposes capabilities such as listing metric keys, searching metrics, retrieving alert details and history, querying logs and traces, listing and retrieving dashboards, and managing services and top operations. Tools are registered as part of the MCP server and can be consumed by MCP clients like Claude Desktop, Cursor, or HTTP-based clients. Once running, clients connect to the MCP endpoint and invoke specific tool commands to fetch data from your SigNoz instance using the API key provided in the environment or client configuration.

To use with Claude Desktop or Cursor, configure an MCP server entry with the server's command path and required environment variables (SigNoz URL and API key). The server supports environment-based configuration (SIGNOZ_URL, SIGNOZ_API_KEY) as well as optional LOG_LEVEL for debugging. When you start the container or binary, the MCP server becomes available at the configured port (default http transport) and exposes tools such as List Metric Keys, Search Metric by Text, Get Alerts, Get Alert Details, Logs, Traces, List Dashboards, Get Dashboard, Create/Update Dashboard, List Services, Service Top Operations, and Query Builder.

Prerequisites:

• Docker installed (for the recommended docker-based run) or a Go toolchain if building locally
• Access to a SigNoz instance with API access and a valid API key
• Git to clone the repository (optional if using prebuilt image)

Option A: Run via Docker (recommended)

1. Pull and run the SigNoz MCP Server docker image (replace with actual image name if different): docker pull signoz/signoz-mcp-server:latest docker run -i
   -e SIGNOZ_URL="https://your-signoz-instance.com"
   -e SIGNOZ_API_KEY="your-api-key-here"
   -e LOG_LEVEL="info"
   -e MCP_SERVER_PORT=8000
   -e TRANSPORT_MODE=http
   signoz/signoz-mcp-server:latest

2. The MCP server should be available at http://localhost:8000/mcp (depending on your container setup). Configure your MCP clients to point to this URL and include the Authorization header if required by your setup.

Option B: Build from Source (Go)

1. Install Go 1.25+ as prerequisites.
2. Clone the repository: git clone https://github.com/SigNoz/signoz-mcp-server.git cd signoz-mcp-server
3. Build the binary: make build

   or direct go build

   go build -o bin/signoz-mcp-server ./cmd/server/
4. Run the server with required env vars: SIGNOZ_URL="https://your-signoz-instance.com" SIGNOZ_API_KEY="your-api-key-here" LOG_LEVEL="info" MCP_SERVER_PORT=8000 ./bin/signoz-mcp-server

Option C: Use docker-compose (if provided in repo)

1. Ensure docker and docker-compose are installed.
2. Follow repository-specific docker-compose.yml to start the MCP server with the appropriate environment variables.

Environment variables and configuration:

• SIGNOZ_URL: Base URL for your SigNoz instance (e.g., https://tenant-slug.region.signoz.cloud or your on-prem URL).
• SIGNOZ_API_KEY: API key with sufficient permissions to query SigNoz data.
• LOG_LEVEL: Logging level (debug, info, warn, error). Default is info.
• MCP_SERVER_PORT: Port where the MCP server will listen (default 8000 if not specified). When using docker, expose the port accordingly.
• TRANSPORT_MODE: http or websocket transport; use http for standard MCP usage.

Common issues:

• Ensure the API key has read access to the SigNoz resources you intend to query.
• If the MCP server cannot reach SigNoz, verify SIGNOZ_URL and network connectivity.
• When using Claude Desktop or Cursor, ensure the client configuration matches either the direct HTTP endpoint or the local Unix path to the running binary, and that the Authorization header is set if required by your setup.
• For production, consider setting LOG_LEVEL=warn or debug temporarily only when actively debugging.