mcp -signoz

This Signoz MCP Server is a Go-based implementation of the Model Context Protocol (MCP) that enables AI assistants and MCP clients to interact with a SigNoz observability stack. It exposes a set of tools to connect to SigNoz, fetch and query dashboards, metrics, traces, logs, and run custom ClickHouse or Builder queries against SigNoz data. The server follows a clean architecture with a dedicated Signoz client, and an MCP transport over STDIO for communication with MCP clients. You can verify connectivity, list dashboards, inspect details, fetch dashboard data, retrieve standard APM metrics, fetch services, execute ClickHouse and builder queries, and obtain traces or logs from Signoz via the MCP interface.

Prerequisites:

• Docker (for containerized run) or Go toolchain if building locally
• Access to a SigNoz instance (URL and API key if required)
• Environment configured as per the Signoz MCP server guidance

Option A: Run via Docker (recommended for quick start)

1. Pull and run the Signoz MCP Server image (example): docker run -i -e SIGNOZ_MCP_SIGNOZ_URL="https://your-signoz-instance.com" -e SIGNOZ_MCP_SIGNOZ_API_KEY="your-api-key" -e SIGNOZ_MCP_SERVER_NAME="signoz-mcp-server" -e SIGNOZ_MCP_SERVER_VERSION="1.0.0" -e SIGNOZ_MCP_LOG_LEVEL="info" calmoai/mcp-server-signoz:latest

2. Ensure the container has access to the SigNoz instance (network access) and required environment variables are set as shown above.

Option B: Build from source (Go)

1. Install Go (1.22+)

2. Clone the repository: git clone https://github.com/CalmoAI/mcp-server-signoz.git cd signoz-mcp-server

3. Build the server: go mod tidy go build -o signoz-mcp-server ./cmd/server

4. Run the server directly (STDIO MCP transport): export SIGNOZ_MCP_SIGNOZ_URL="https://your-signoz-instance.com" export SIGNOZ_MCP_SIGNOZ_API_KEY="your-api-key" ./signoz-mcp-server

5. Optional: use configuration file config.yaml or environment variable overrides as described in the README.

Tips and common issues:

• The server relies on environment variables with the SIGNOZ_MCP_ prefix. Use SIGNOZ_MCP_SIGNOZ_URL as a required value and SIGNOZ_MCP_SIGNOZ_API_KEY if authentication is needed.
• If you run via Docker, ensure the container has network access to the SigNoz instance and any required TLS settings are properly configured (TLS enabled by default in Signoz config).
• For performance, review the Signoz_MCP_SIGNOZ_MAX_CONNECTIONS and timeout-related settings to match your load.
• When debugging, you can enable verbose logging by setting SIGNOZ_MCP_LOG_LEVEL to debug and SIGNOZ_MCP_LOG_FORMAT to text.
• The MCP server communicates over STDIO with MCP clients; ensure your client is configured to send and receive MCP messages on STDIO as per the protocol.
• If you modify configuration, prefer environment variables over config.yaml due to precedence rules.