MCP (Model Context Protocol) is an open-source standard for connecting AI applications to external systems.
Signoz MCP Server lets AI assistance and LLMs connect to Signoz observability data. Integration of signoz-mcp-server with LLMs and AI assistance like Cursor or Claude enables you to query in natural language and get more precise and structured information.
Working
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ MCP Client │───▶│ MCP Server │───▶│ SigNoz API │
│ (AI Assistant) │ │ (Go) │ │ (Observability)│
└─────────────────┘ └──────────────────┘ └─────────────────┘
│
▼
┌──────────────────┐
│ Tool Handlers │
│ (HTTP Client) │
└──────────────────┘
📌 Note: Signoz MCP Server is ready for use but under heavy development and its expected to see changes. Early feedback is appreciated.
Current state of signoz-mcp-server provides tools as mentioned below.
- List Metric Keys: Retrieve all available metric keys from SigNoz
- Search Metric Keys: Find specific metrics
- List Alerts: Get all active alerts with detailed status
- Get Alert Details: Retrieve comprehensive information about specific alert rules
- Get Alert History: Timeline of alert history for specific rules
- Get Logs for Alert: Logs related to specific alerts automatically
- Get Error Logs: Logs with ERROR or FATAL severity
- Search Logs by Service: Search logs for specific services with filters
- List Log Views: Get all saved log views
- Get Log View: Retrieve complete log view configuration
- List Dashboards: Get dashboard summaries (name, UUID, description, tags)
- Get Dashboard: Retrieve complete dashboard configurations with panels and queries
- List Services: Discover all services within specified time ranges
- Service Top Operations: Analyze performance metrics for specific services
- Get Trace Field Values: Available field values for trace queries
- Search Traces by Service: Search traces with filters (errors, duration, operation)
- Get Trace Details: Comprehensive trace information with all spans and metadata
- Get Trace Error Analysis: Analyze error patterns in traces
- Get Trace Span Hierarchy: Trace span relationships and hierarchy
Core Components
- MCP Server: Handles MCP protocol communication
- Tool Handlers: Register and manage available tools
- SigNoz Client: HTTP client for SigNoz API interactions
- Configuration: Environment-based configuration management
- Logging: Structured logging with Zap
Installation
The SigNoz MCP Server is available as open-source software on GitHub: https://github.com/SigNoz/signoz-mcp-server
Building from Source:
- Clone the repository:
git clone https://github.com/SigNoz/signoz-mcp-server.git
cd signoz-mcp-server
- Build the binary:
make build
The binary will be created at bin/signoz-mcp-server.
Using Docker:
You can also run the MCP server using Docker Compose. See the repository for docker-compose configuration examples.
Integrations
In current state signoz-mcp-server can be integrated with Stdio or http mode, tested with Cursor and Claude.
Claude Desktop
Stdio based
- Build or locate the binary path for
signoz-mcp-server(for example:.../signoz-mcp-server/bin/signoz-mcp-server). - Go to Claude -> Settings -> Developer -> Local MCP Server click on
edit config - Edit
claude_desktop_config.jsonAdd shown config with your signoz url, api key and path to signoz-mcp-server binary.
{
"mcpServers": {
"signoz": {
"command": "/absolute/path/to/signoz-mcp-server/bin/signoz-mcp-server",
"args": [],
"env": {
"SIGNOZ_URL": "https://your-signoz-instance.com",
"SIGNOZ_API_KEY": "your-api-key-here",
"LOG_LEVEL": "info"
}
}
}
}
- Restart Claude Desktop. You should see the
signozserver load in the developer console and its tools become available.
📌 Note: Replace the
commandpath with your actual binary location.
HTTP based
HTTP mode supports two authentication methods:
Method 1: Environment Variable
- Build and run signoz-mcp-server with API key in environment:
SIGNOZ_URL=signoz_url SIGNOZ_API_KEY=signoz_apikey TRANSPORT_MODE=http MCP_SERVER_PORT=8000 LOG_LEVEL=log_level ./signoz-mcp-server
Or use docker-compose.
- Go to Claude -> Settings -> Developer -> Local MCP Server click on
edit config - Edit
claude_desktop_config.json:
{
"mcpServers": {
"signoz": {
"url": "http://localhost:8000/mcp"
}
}
}
Method 2: Authorization Header
- Build and run signoz-mcp-server without API key in environment:
SIGNOZ_URL=signoz_url TRANSPORT_MODE=http MCP_SERVER_PORT=8000 LOG_LEVEL=log_level ./signoz-mcp-server
- Go to Claude -> Settings -> Developer -> Local MCP Server click on
edit config - Edit
claude_desktop_config.jsonwith API key in Authorization header:
{
"mcpServers": {
"signoz": {
"url": "http://localhost:8000/mcp",
"headers": {
"Authorization": "Bearer your-signoz-api-key-here"
}
}
}
}
This method allows application-level access control and is ideal for hosted MCP servers or multi-tenant scenarios.
- Restart Claude Desktop. You should see the
signozserver load in the developer console and its tools become available.
Cursor
Stdio based
Option A — GUI:
- Open Cursor → Settings → Cursor Settings → Tool & Integrations →
+New MCP Server
Option B — Project config file: Create .cursor/mcp.json in your project root:
For Both options use same json struct
{
"mcpServers": {
"signoz": {
"command": "/absolute/path/to/signoz-mcp-server/bin/signoz-mcp-server",
"args": [],
"env": {
"SIGNOZ_URL": "https://your-signoz-instance.com",
"SIGNOZ_API_KEY": "your-api-key-here",
"LOG_LEVEL": "info"
}
}
}
}
Once added, restart Cursor to use the SigNoz tools.
HTTP based
HTTP mode supports two authentication methods:
Method 1: Environment Variable
Build and run signoz-mcp-server with API key in environment:
SIGNOZ_URL=signoz_url SIGNOZ_API_KEY=signoz_apikey TRANSPORT_MODE=http MCP_SERVER_PORT=8000 LOG_LEVEL=log_level ./signoz-mcp-server
Or use docker-compose.
Option A — GUI:
- Open Cursor → Settings → Cursor Settings → Tool & Integrations →
+New MCP Server
Option B — Project config file:
- Create
.cursor/mcp.jsonin your project root
For both options use this JSON structure:
{
"mcpServers": {
"signoz": {
"url": "http://localhost:8000/mcp"
}
}
}
Method 2: Authorization Header
Build and run signoz-mcp-server without API key in environment:
SIGNOZ_URL=signoz_url TRANSPORT_MODE=http MCP_SERVER_PORT=8000 LOG_LEVEL=log_level ./signoz-mcp-server
Option A — GUI:
- Open Cursor → Settings → Cursor Settings → Tool & Integrations →
+New MCP Server
Option B — Project config file:
- Create
.cursor/mcp.jsonin your project root
For both options use this JSON structure with Authorization header:
{
"mcpServers": {
"signoz": {
"url": "http://localhost:8000/mcp",
"headers": {
"Authorization": "Bearer your-signoz-api-key-here"
}
}
}
}
📌 Note: By default, the server logs at
infolevel. If you need detailed debugging information, setLOG_LEVEL=debugin your environment. For production use, consider usingLOG_LEVEL=warnto reduce log verbosity.