signoz-mcp-server

joshualyon/signoz-mcp-server

3.1

If you are the rightful owner of signoz-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Signoz MCP Server is a Model Context Protocol server that provides access to Signoz observability data, allowing for natural language queries against logs, metrics, and traces.

Tools
3
Resources
0
Prompts
0

Signoz MCP Server

An MCP (Model Context Protocol) server that exposes Signoz observability data to Claude, enabling natural language queries against your logs, metrics, and traces.

Features

  • Query Logs: Search and analyze application logs with simple filter syntax
  • Query Metrics: Builder-based metrics querying with aggregation and grouping
  • Discover Data: Explore available metrics and log attributes
  • Unified Interface: Consistent syntax across logs and metrics
  • Type Safety: Robust timestamp handling and parameter validation
  • Production Ready: Comprehensive test coverage and error handling

āœ… Implemented

  • āœ… Logs: Querying with pagination and attribute filtering
  • āœ… Metrics: Builder queries with multiple metrics, aggregation, and grouping
  • āœ… Discovery: Metric and log attribute discovery tools
  • āœ… Testing: 45+ tests covering all functionality

šŸš§ In Development

  • šŸš§ Traces: Placeholder - not functional

Prerequisites

  • Signoz 0.85 or later (for API v4 support)
  • Signoz API key
  • One of:
    • Bun runtime (for development)
    • Pre-built binary from Releases

Installation

Option 1: Using Pre-built Binaries (Recommended)

Download the appropriate binary for your platform from the Releases page:

  • signoz-mcp-darwin-arm64 - macOS Apple Silicon
  • signoz-mcp-darwin-x64 - macOS Intel
  • signoz-mcp-linux-x64 - Linux x64
  • signoz-mcp-linux-arm64 - Linux arm64
  • signoz-mcp-windows-x64.exe - Windows x64

Make it executable (macOS/Linux):

chmod +x signoz-mcp-*

[!IMPORTANT] macOS Users: Downloaded binaries are quarantined by Gatekeeper. You have three options:

  1. Remove quarantine: xattr -d com.apple.quarantine ./signoz-mcp-darwin-*
  2. Run from source using Bun (see Option 2 below)
  3. Build the binary locally: bun run build

Option 2: Build from Source

# Clone the repository
git clone <repository-url>
cd signoz-mcp-server

# Install dependencies
bun install

Configuration

Claude Code Integration

There are multiple ways to configure the Signoz MCP server with Claude Code:

Method 1: Project Configuration File (Recommended)

Create a .mcp.json file in your project root:

{
  "mcpServers": {
    "signoz": {
      "type": "stdio",
      "command": "/path/to/signoz-mcp-server-binary",
      "env": {
        "SIGNOZ_API_KEY": "your-api-key-here",
        "SIGNOZ_API_URL": "https://your-signoz-instance.com"
      }
    }
  }
}

Or if running from source:

{
  "mcpServers": {
    "signoz": {
      "type": "stdio",
      "command": "bun",
      "args": ["run", "/path/to/signoz-mcp-server/src/server.ts"],
      "env": {
        "SIGNOZ_API_KEY": "your-api-key-here",
        "SIGNOZ_API_URL": "https://your-signoz-instance.com"
      }
    }
  }
}

After creating the file:

  1. Exit Claude Code: /exit
  2. Restart in the same directory: claude -c
  3. Verify the server is loaded: /mcp

[!TIP] Using claude -c will continue your previous Claude Code session, so you won't lose any progress and can continue your existing conversation where you left off.

Method 2: Claude CLI Management
# Add server with binary (local to current project)
claude mcp add signoz -s project -e SIGNOZ_API_KEY=your-key -e SIGNOZ_API_URL=https://your-instance.com -- /path/to/signoz-mcp-server-binary

# Add server from source
claude mcp add signoz -s project -e SIGNOZ_API_KEY=your-key -e SIGNOZ_API_URL=https://your-instance.com -- bun run /path/to/signoz-mcp-server/src/server.ts

# List configured servers
claude mcp list

# View server configuration
claude mcp get signoz

# Remove server
claude mcp remove signoz

Scope Options:

  • --scope local (default): Available only in current project
  • --scope project: Shared via .mcp.json file
  • --scope user: Available across all projects

[!NOTE] Local scope configurations are stored in ~/.claude.json under:

{
  "projects": {
    "/path/to/project": {
      "mcpServers": {
        // your server config here
      }
    }
  }
}
Method 3: Claude Desktop App

See for Claude Desktop configuration details and refer to the example JSON snippets from Method 1 above.

Usage

Development

bun run dev

Testing with MCP Inspector

bun run inspector

This will start the MCP Inspector on http://localhost:6274 where you can interactively test the server's tools.

Build

bun run build

Quick Test

bun run test

Available Tools

query_logs

Query application logs from Signoz using simplified filter syntax with clean, readable output.

Key Features:

  • Minimal Output by Default: Clean [timestamp] [level] [service-context] message format
  • Smart Service Context: Shows [service-name] or [namespace/deployment] automatically
  • Verbose Mode: Full attribute details when needed (verbose: true)
  • Attribute Filtering: Include only specific attributes (include_attributes: [...])
  • Automatic Pagination: Handles large result sets with clear instructions for next page

The tool accepts simple filter syntax with these operators:

  • key=value - Exact match
  • key~value - Contains (useful for searching in log body)
  • key!=value - Not equals

Join multiple filters with AND:

  • k8s.deployment.name=stio-api - Filter by Kubernetes deployment
  • level=error AND service=api-gateway - Multiple filters
  • body~timeout - Logs containing "timeout" in the message
  • k8s.namespace=production AND body~error - Combine resource and content filters

Output Examples:

Default Compact Mode:

[2025-06-17T22:26:42Z] [INFO] [default/stio-api]
Set variable $GridPower value as 1.3377999999999999.

[2025-06-17T22:26:41Z] [ERROR] [api-gateway]
Database connection timeout after 30s

[2025-06-17T22:26:40Z] [WARN] [production/user-service]
Rate limit approaching: 450/500 requests

Verbose Mode (verbose: true):

[2025-06-17T22:26:42Z] [INFO] [default/stio-api]
Set variable $GridPower value as 1.3377999999999999.
Attributes: http.request.id=abc-123 labels.module=rule trace.id=xyz-789

[2025-06-17T22:26:41Z] [ERROR] [api-gateway]
Database connection timeout after 30s
Attributes: error.type=timeout database.name=users http.status=500

Custom Attributes (include_attributes: ["http.request.id", "trace.id"]):

[2025-06-17T22:26:42Z] [INFO] [default/stio-api]
Set variable $GridPower value as 1.3377999999999999.
Attributes: http.request.id=abc-123 trace.id=xyz-789

Query Examples:

"Show logs from the stio-api deployment"
ā†’ query: "k8s.deployment.name=stio-api"

"Find error logs from the api-gateway service in the last hour"
ā†’ query: "level=error AND service=api-gateway", start: "now-1h"

"Get logs containing 'timeout' from production namespace"
ā†’ query: "k8s.namespace=production AND body~timeout"

"Find logs with database errors, showing trace IDs"
ā†’ query: "body~database AND body~error", include_attributes: ["trace.id"]

"Debug logs with full details"
ā†’ query: "level=debug AND service=user-api", verbose: true

Pagination Example: When results exceed the limit, the tool provides clear instructions:

--- More Results Available ---
Oldest timestamp: 2025-06-17T23:09:19.025991988Z
To get next 100 older results, use: end="2025-06-17T23:09:19.025991988Z"

query_metrics

Query metrics using a builder-based interface with aggregation and grouping.

Key Features:

  • Multiple Metrics: Query multiple metrics in one request
  • Aggregation Options: avg, min, max, sum, count
  • Grouping: Group results by attributes
  • Filter Syntax: Same as logs (key=value, key~contains, key!=value)

Examples:

"Show CPU utilization for the stio-api deployment"
ā†’ metric: ["k8s_pod_cpu_utilization"], query: "k8s_deployment_name=stio-api"

"Compare CPU and memory usage grouped by pod"
ā†’ metric: ["k8s_pod_cpu_utilization", "k8s_pod_memory_usage"], 
  group_by: ["k8s_pod_name"], aggregation: "avg"

"Get maximum request rates by status code"
ā†’ metric: ["http_requests_total"], group_by: ["status_code"], 
  aggregation: "max", query: "service=api-gateway"

query_traces

Query distributed traces.

Example:

"Find traces where the total duration exceeded 1 second"

Documentation

  • - Comprehensive examples of log queries and output formats
  • - Build, test, and release processes
  • - Setup and troubleshooting
  • - Signoz API details and examples
  • - Feature roadmap and design decisions

Development

Building

# Build for current platform
bun run build

# Build for all platforms
bun run build:binary:all

# Run tests
bun test

Releases

This project uses automated semantic versioning. See for details on:

  • Commit message conventions
  • Automated release process
  • Manual release procedures

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feat/amazing-feature)
  3. Commit changes using conventional commits (git commit -m 'feat: add amazing feature')
  4. Push to the branch (git push origin feat/amazing-feature)
  5. Open a Pull Request to main

License

MIT