Content
# Signoz MCP Server
A Go implementation of a Model Context Protocol (MCP) server that provides seamless integration with [SigNoz](https://signoz.io/), an open-source observability platform. This server enables AI assistants and other MCP clients to interact with SigNoz APIs for querying dashboards, metrics, traces, logs, and more.
## Features
The Signoz MCP Server provides the following tools:
- **`signoz_test_connection`**: Verify connectivity to your Signoz instance and configuration
- **`signoz_fetch_dashboards`**: List all available dashboards from Signoz
- **`signoz_fetch_dashboard_details`**: Retrieve detailed information about a specific dashboard by its ID
- **`signoz_fetch_dashboard_data`**: Fetch all panel data for a given dashboard by name and time range
- **`signoz_fetch_apm_metrics`**: Retrieve standard APM metrics (request rate, error rate, latency, apdex) for a given service and time range
- **`signoz_fetch_services`**: Fetch all instrumented services from Signoz with optional time range filtering
- **`signoz_execute_clickhouse_query`**: Execute custom ClickHouse SQL queries via the Signoz API with time range support
- **`signoz_execute_builder_query`**: Execute Signoz builder queries for custom metrics and aggregations with time range support
- **`signoz_fetch_traces_or_logs`**: Fetch traces or logs from SigNoz using ClickHouse SQL
## Architecture
This project follows Clean Architecture principles with the following structure:
```
├── cmd/server/ # Application entry point
├── internal/
│ ├── domain/ # Domain models and interfaces
│ ├── application/service/ # Application services
│ └── infrastructure/ # External integrations
│ ├── config/ # Configuration management
│ └── signoz/ # Signoz API client
├── pkg/mcp/ # MCP protocol implementation
│ ├── transport/ # Transport layer (STDIO)
│ └── server/ # MCP server implementation
└── configs/ # Configuration files
```
## Prerequisites
- Go 1.22 or later
- Access to a SigNoz instance
- SigNoz API key (if authentication is required)
## Installation
### Option 1: Build from Source
1. Clone the repository:
```bash
git clone https://github.com/CalmoAI/mcp-server-signoz.git
cd signoz-mcp-server
```
2. Install and update dependencies:
```bash
go mod tidy
```
3. Build the server:
```bash
go build -o signoz-mcp-server ./cmd/server
```
4. (Optional) Get the absolute path for configuration:
```bash
pwd
# This will show the full path to your binary: /path/to/signoz-mcp-server
```
5. Verify the installation:
```bash
# Test that the binary runs (it will start the MCP server)
./signoz-mcp-server
# Press Ctrl+C to stop the server
```
### Option 2: Install with Go
```bash
go install github.com/CalmoAI/mcp-server-signoz/cmd/server@latest
```
## Configuration
The server can be configured using environment variables, configuration files, or command-line flags.
### Environment Variables
**ANY configuration value** can be overridden using environment variables with the `SIGNOZ_MCP_` prefix. This provides complete flexibility for deployment and runtime configuration.
#### Environment Variable Pattern
```
SIGNOZ_MCP_<SECTION>_<KEY>
```
#### Examples
```bash
# Core SigNoz configuration
export SIGNOZ_MCP_SIGNOZ_URL="https://your-signoz-instance.com"
export SIGNOZ_MCP_SIGNOZ_API_KEY="your-api-key"
# Logging configuration
export SIGNOZ_MCP_LOG_LEVEL="debug"
export SIGNOZ_MCP_LOG_FORMAT="text"
# Server configuration
export SIGNOZ_MCP_SERVER_TIMEOUT="60s"
export SIGNOZ_MCP_SERVER_DEBUG="true"
# Telemetry configuration
export SIGNOZ_MCP_TELEMETRY_ENABLED="false"
```
#### Complete Environment Variable Reference
**Server Configuration:**
- `SIGNOZ_MCP_SERVER_NAME` - Server name (default: "signoz-mcp-server")
- `SIGNOZ_MCP_SERVER_VERSION` - Server version (default: "1.0.0")
- `SIGNOZ_MCP_SERVER_ENVIRONMENT` - Environment (default: "development")
- `SIGNOZ_MCP_SERVER_DEBUG` - Enable debug mode (default: false)
- `SIGNOZ_MCP_SERVER_TIMEOUT` - Server timeout (default: "30s")
**SigNoz Configuration:**
- `SIGNOZ_MCP_SIGNOZ_URL` - SigNoz instance URL (required)
- `SIGNOZ_MCP_SIGNOZ_API_KEY` - API key for authentication
- `SIGNOZ_MCP_SIGNOZ_TIMEOUT` - Request timeout (default: "30s")
- `SIGNOZ_MCP_SIGNOZ_RETRY_ATTEMPTS` - Number of retry attempts (default: 3)
- `SIGNOZ_MCP_SIGNOZ_RETRY_DELAY` - Initial retry delay (default: "1s")
- `SIGNOZ_MCP_SIGNOZ_MAX_RETRY_DELAY` - Maximum retry delay (default: "30s")
- `SIGNOZ_MCP_SIGNOZ_TLS_ENABLED` - Enable TLS (default: true)
- `SIGNOZ_MCP_SIGNOZ_TLS_SKIP_VERIFY` - Skip TLS verification (default: false)
- `SIGNOZ_MCP_SIGNOZ_MAX_CONNECTIONS` - Max HTTP connections (default: 100)
- `SIGNOZ_MCP_SIGNOZ_IDLE_TIMEOUT` - Connection idle timeout (default: "90s")
- `SIGNOZ_MCP_SIGNOZ_KEEP_ALIVE` - Keep-alive duration (default: "30s")
**Logging Configuration:**
- `SIGNOZ_MCP_LOG_LEVEL` - Log level: debug, info, warn, error, fatal (default: "info")
- `SIGNOZ_MCP_LOG_FORMAT` - Log format: json, text (default: "json")
- `SIGNOZ_MCP_LOG_OUTPUT` - Log output: stdout, stderr (default: "stderr")
- `SIGNOZ_MCP_LOG_STRUCTURED` - Structured logging (default: true)
**Telemetry Configuration:**
- `SIGNOZ_MCP_TELEMETRY_ENABLED` - Enable telemetry (default: true)
- `SIGNOZ_MCP_TELEMETRY_SERVICE_NAME` - Service name (default: "signoz-mcp-server")
- `SIGNOZ_MCP_TELEMETRY_SERVICE_VERSION` - Service version (default: "1.0.0")
- `SIGNOZ_MCP_TELEMETRY_ENVIRONMENT` - Environment (default: "development")
- `SIGNOZ_MCP_TELEMETRY_TRACE_ENDPOINT` - Trace endpoint URL
- `SIGNOZ_MCP_TELEMETRY_METRICS_ENDPOINT` - Metrics endpoint URL
- `SIGNOZ_MCP_TELEMETRY_SAMPLE_RATE` - Sampling rate 0-1 (default: 1.0)
- `SIGNOZ_MCP_TELEMETRY_BATCH_TIMEOUT` - Batch timeout (default: "5s")
- `SIGNOZ_MCP_TELEMETRY_EXPORT_TIMEOUT` - Export timeout (default: "30s")
- `SIGNOZ_MCP_TELEMETRY_MAX_EXPORT_BATCH_SIZE` - Max batch size (default: 512)
**Cache Configuration:**
- `SIGNOZ_MCP_CACHE_ENABLED` - Enable caching (default: true)
- `SIGNOZ_MCP_CACHE_TTL` - Cache TTL (default: "5m")
- `SIGNOZ_MCP_CACHE_MAX_ENTRIES` - Max cache entries (default: 1000)
#### Configuration Precedence
1. **Environment Variables** (highest priority)
2. **Configuration File** (config.yaml)
3. **Default Values** (lowest priority)
### Configuration File
Create a `config.yaml` file in the current directory, `./configs/`, or `/etc/signoz-mcp-server/`:
```yaml
server:
name: "signoz-mcp-server"
version: "1.0.0"
environment: "production"
debug: false
timeout: "30s"
signoz:
url: "https://your-signoz-instance.com"
api_key: "your-api-key"
timeout: "30s"
retry_attempts: 3
retry_delay: "1s"
max_retry_delay: "30s"
tls_enabled: true
tls_skip_verify: false
max_connections: 100
idle_timeout: "90s"
keep_alive: "30s"
log:
level: "info"
format: "json"
output: "stdout"
structured: true
telemetry:
enabled: true
service_name: "signoz-mcp-server"
service_version: "1.0.0"
environment: "production"
sample_rate: 1.0
batch_timeout: "5s"
export_timeout: "30s"
max_export_batch_size: 512
cache:
enabled: true
ttl: "5m"
max_entries: 1000
```
### Required Configuration
The only required configuration is the Signoz URL:
- `SIGNOZ_MCP_SIGNOZ_URL` or `signoz.url` in config file
Optional but recommended:
- `SIGNOZ_MCP_SIGNOZ_API_KEY` or `signoz.api_key` for authenticated access
## Usage
### Running the Server
```bash
# Using environment variables
export SIGNOZ_MCP_SIGNOZ_URL="https://your-signoz-instance.com"
export SIGNOZ_MCP_SIGNOZ_API_KEY="your-api-key"
./signoz-mcp-server
# Using configuration file
./signoz-mcp-server
```
The server will start and communicate over STDIO following the MCP protocol specification.
### Integration with Claude Desktop
Add the server to your Claude Desktop configuration:
```json
{
"mcpServers": {
"signoz": {
"command": "/absolute/path/to/signoz-mcp-server",
"env": {
"SIGNOZ_MCP_SIGNOZ_URL": "https://your-signoz-instance.com",
"SIGNOZ_MCP_SIGNOZ_API_KEY": "your-api-key"
}
}
}
}
```
**Note:** Replace `/absolute/path/to/signoz-mcp-server` with the full path to your built binary.
### Integration with Cursor IDE
Add the server to your Cursor IDE MCP configuration. Create or update your MCP configuration file:
**For macOS/Linux** (`~/.cursor/mcp_servers.json`):
```json
{
"mcpServers": {
"signoz": {
"command": "/absolute/path/to/signoz-mcp-server",
"env": {
"SIGNOZ_MCP_SIGNOZ_URL": "https://your-signoz-instance.com",
"SIGNOZ_MCP_SIGNOZ_API_KEY": "your-api-key"
}
}
}
}
```
**For Windows** (`%APPDATA%\Cursor\mcp_servers.json`):
```json
{
"mcpServers": {
"signoz": {
"command": "C:\\absolute\\path\\to\\signoz-mcp-server.exe",
"env": {
"SIGNOZ_MCP_SIGNOZ_URL": "https://your-signoz-instance.com",
"SIGNOZ_MCP_SIGNOZ_API_KEY": "your-api-key"
}
}
}
}
```
**Configuration Notes:**
- Replace `/absolute/path/to/signoz-mcp-server` with the full path to your built binary
- The `SIGNOZ_MCP_SIGNOZ_API_KEY` is optional if your SigNoz instance doesn't require authentication
- Ensure the binary has execute permissions (`chmod +x signoz-mcp-server` on Unix systems)
**Using the Integration:**
1. Restart Cursor IDE after updating the configuration
2. The SigNoz tools will be automatically available in Cursor's AI assistant
3. You can directly ask Cursor to use SigNoz commands like:
- "Test my SigNoz connection"
- "Show me all dashboards from SigNoz"
- "Get APM metrics for my-service"
- "Execute this ClickHouse query on SigNoz"
### Integration with Other MCP Clients
The server implements the standard MCP protocol and can be used with any compatible MCP client. Refer to your client's documentation for specific integration instructions.
## Tool Usage Examples
### Test Connection
```
Use the signoz_test_connection tool to verify your Signoz instance is accessible.
```
### Fetch Dashboards
```
Use signoz_fetch_dashboards to get a list of all available dashboards.
```
### Fetch Dashboard Details
```
Use signoz_fetch_dashboard_details with dashboard_id: "your-dashboard-id" to get detailed information about a specific dashboard.
```
### Fetch Dashboard Data
```
Use signoz_fetch_dashboard_data with:
- dashboard_name: "My Dashboard"
- start_time: "2023-12-01T00:00:00Z"
- end_time: "2023-12-01T01:00:00Z"
```
### Fetch APM Metrics
```
Use signoz_fetch_apm_metrics with:
- service_name: "my-service"
- start_time: "2023-12-01T00:00:00Z"
- end_time: "2023-12-01T01:00:00Z"
```
### Execute ClickHouse Query
```
Use signoz_execute_clickhouse_query with:
- sql: "SELECT * FROM signoz_traces.signoz_spans WHERE service_name = 'my-service' LIMIT 100"
- start_time: "2023-12-01T00:00:00Z"
- end_time: "2023-12-01T01:00:00Z"
```
## Development
### Prerequisites
- Go 1.22+
- Make (optional, for using Makefile)
### Setup
1. Clone the repository
2. Install dependencies: `go mod download`
3. Run tests: `go test ./...`
4. Build: `go build -o signoz-mcp-server cmd/server/main.go`
### Project Structure
- **Domain Layer** (`internal/domain/`): Core business logic and interfaces
- **Application Layer** (`internal/application/`): Use cases and application services
- **Infrastructure Layer** (`internal/infrastructure/`): External dependencies and implementations
- **Presentation Layer** (`pkg/mcp/`): MCP protocol handling
### Testing
Run the test suite:
```bash
# Run all tests
go test ./...
# Run tests with coverage
go test -cover ./...
# Run tests with race detection
go test -race ./...
```
### Adding New Tools
1. Define the tool interface in `internal/domain/interfaces.go`
2. Implement the business logic in `internal/application/service/mcp_service.go`
3. Add the tool definition in `pkg/mcp/server/server.go`
4. Add tool execution logic in the `executeTool` method
## Security Considerations
- **API Keys**: Store API keys securely using environment variables or secure configuration management
- **Network Security**: Use HTTPS for Signoz connections in production
- **Input Validation**: All user inputs are validated before processing
- **Rate Limiting**: Built-in rate limiting to prevent API abuse
- **Error Handling**: Errors are logged but sensitive information is not exposed
## Performance
The server includes several performance optimizations:
- **Caching**: Configurable caching for frequently accessed data
- **Connection Pooling**: HTTP connection pooling for efficient Signoz API calls
- **Rate Limiting**: Protection against API rate limits
- **Retry Logic**: Exponential backoff for failed requests
- **Timeouts**: Configurable timeouts to prevent hanging requests
## Troubleshooting
### Common Issues
1. **Connection Failed**
- Verify Signoz URL is correct and accessible
- Check network connectivity
- Ensure API key is valid (if required)
2. **Authentication Errors**
- Verify API key is correct
- Check API key permissions in Signoz
3. **Query Failures**
- Verify time ranges are valid
- Check dashboard/service names exist
- Review ClickHouse query syntax
### Logging
Enable debug logging for detailed troubleshooting:
```bash
export SIGNOZ_MCP_LOG_LEVEL="debug"
./signoz-mcp-server
```
### Health Checks
Use the `signoz_test_connection` tool to verify server health and Signoz connectivity.
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
### Development Guidelines
- Follow Go conventions and best practices
- Write tests for new functionality
- Update documentation for API changes
- Use semantic commit messages
- Ensure all tests pass before submitting
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
- **Issues**: [GitHub Issues](https://github.com/CalmoAI/mcp-server-signoz/issues)
- **Discussions**: [GitHub Discussions](https://github.com/CalmoAI/mcp-server-signoz/discussions)
- **Documentation**: [Project Wiki](https://github.com/CalmoAI/mcp-server-signoz/wiki)
## Acknowledgments
- [SigNoz](https://signoz.io/) for the excellent observability platform
- [Anthropic](https://www.anthropic.com/) for the Model Context Protocol specification
- The Go community for excellent libraries and tools
- [Calmo](https://getcalmo.com/) Team for building it
Connection Info
You Might Also Like
No recommendations available