Signoz Mcp Server
About
The Signoz MCP Server lets you connect developer tools like Cursor or Claude Desktop to your Signoz instance. It's an open-source project maintained by DrDroid (not affiliated with Signoz), and allows you to query logs, dashboards, metrics, and more — making observability data di
Details
- Author
- DrDroidLab
- Downloads
- 382
- Categories
- Developer Tools
Jump to
- Test connectivity to your SigNoz instance.
- List and retrieve details of all dashboards.
- Fetch live panel data for a dashboard by name and time range.
- Retrieve APM metrics (request rate, error rate, latency, apdex) per service.
- List all instrumented services with optional time range filtering.
- Execute custom ClickHouse SQL queries and builder queries via SigNoz API.
- Fetch traces or logs using ClickHouse SQL with service filtering.
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Signoz Mcp ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Install dependencies with uv sync, then run with uv run -m src.signoz_mcp_server.mcp_server. Alternatively, deploy using Docker Compose or Docker with environment variables. Configure via config.yaml or environment variables (SIGNOZ_HOST, SIGNOZ_API_KEY, etc.). Integrate with AI assistants using stdio mode or HTTP/SSE endpoint.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"signoz mcp server": {
"signoz": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"SIGNOZ_HOST",
"-e",
"SIGNOZ_API_KEY",
"-e",
"SIGNOZ_SSL_VERIFY",
"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"
}
}
}
}
}McpServers
{
"signoz": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"SIGNOZ_HOST",
"-e",
"SIGNOZ_API_KEY",
"-e",
"SIGNOZ_SSL_VERIFY",
"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"
}
}
}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
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).
---
2C. Run with Docker Image (Manual)
1. Build the image:
docker build -t signoz-mcp-server .
2. Run the container (YAML config fallback):
docker run -d \
-p 8000:8000 \
-v $(pwd)/src/signoz_mcp_server/config.yaml:/app/config.yaml:ro \
--name signoz-mcp-server \
signoz-mcp-server
3. Or run with environment variables (recommended for CI/Docker MCP clients):
docker run -d \
-p 8000:8000 \
-e SIGNOZ_HOST="https://your-signoz-instance.com" \
-e SIGNOZ_API_KEY="your-signoz-api-key-here" \
-e SIGNOZ_SSL_VERIFY="true" \
-e MCP_SERVER_PORT=8000 \
-e MCP_SERVER_DEBUG=true \
--name signoz-mcp-server \
signoz-mcp-server
---
3. 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
---
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 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": "uv",
"args": ["run", "/full/path/to/src/signoz_mcp_server/mcp_server.py"],
"env": {
"SIGNOZ_HOST": "https://your-signoz-instance.com",
"SIGNOZ_API_KEY": "your-signoz-api-key-here",
"SIGNOZ_SSL_VERIFY": "true"
}
}
}
}
- 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",
"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.
---
5. Miscellaneous:
1. Need help anywhere? Join our slack community and message on #mcp channel.
2. Want a 1-click MCP Server? Join the same comunity and let us know.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
