Signoz MCP Server
Watch Working Demo on Cursor 📽️ https://youtube.com/shorts/jxjmGyXXz7A
Available Tools
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.
🚀 Usage & Requirements
1. Get Your Signoz API Endpoint & (Optional) API Key
- Ensure you have a running Signoz instance (self-hosted or cloud).
- (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
uvto run any other entrypoint scripts as needed. - Make sure your
config.yamlis in the same directory asmcp_server.pyor set the required environment variables (see Configuration section).
2B. Run with Docker Compose (Recommended for Production/Containerized Environments)
- Edit
src/signoz_mcp_server/config.yamlwith your Signoz details (host, API key if needed). - 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).
3. Configuration
The server loads configuration in the following order of precedence:
- 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:trueorfalse(default:true)MCP_SERVER_PORT: Port to run the server on (default:8000)MCP_SERVER_DEBUG:trueorfalse(default:true)
- 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
4. Integration with AI Assistants (e.g., Claude Desktop, Cursor)
You can integrate this MCP server with any tool that supports the MCP protocol. Here are the main options:
4A. 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",
"drdroidlab/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 stdioargument 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-hostwith the actual host where your MCP server is running. - For local setup, use
localhostas the server host (i.e.,http://localhost:8000/mcp). - Use
httpfor local or unsecured deployments, andhttpsfor 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-hostwith the actual host where your MCP server is running. - For local setup, use
localhostas the server host (i.e.,http://localhost:8000/mcp). - Use
httporhttpsin the URL schema depending on how you've deployed the MCP server. - No need to specify
commandorargs—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.
5. Miscellaneous:
- Need help anywhere? Join our slack community and message on #mcp channel.
- Want to try without setting up? Follow this doc for a quickstart on DrDroid cloud platform.
Metadata
Release files for iflow-mcp_signoz-mcp-server 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_signoz_mcp_server-0.1.0.tar.gz | 2.0 MB | Without provenance | Details for iflow_mcp_signoz_mcp_server-0.1.0.tar.gz |
Release files / iflow_mcp_signoz_mcp_server-0.1.0.tar.gz
| Download URL | iflow_mcp_signoz_mcp_server-0.1.0.tar.gz |
|---|---|
| Size | 2.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ddc76c4f847577ff4a6e03a7750910786bb3a832541b0b4e227295860971a305
|
|
BLAKE2b-256 checksum How to use checksums |
a679b978c0f2674f3f44e19c3a0f0abf0c7fe07818ccf53dac847b27c2a870b6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.10 {"installer":{"name":"uv","version":"0.9.10"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_signoz-mcp-server 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.