Skip to content

feat: add signoz_execute_clickhouse_query MCP tool via v3 API#62

Open
nilaydown wants to merge 1 commit intoSigNoz:mainfrom
nilaydown:feat/clickhouse-sql-v3-query-tool
Open

feat: add signoz_execute_clickhouse_query MCP tool via v3 API#62
nilaydown wants to merge 1 commit intoSigNoz:mainfrom
nilaydown:feat/clickhouse-sql-v3-query-tool

Conversation

@nilaydown
Copy link
Copy Markdown

@nilaydown nilaydown commented Mar 3, 2026

Summary

  • Add signoz_execute_clickhouse_query MCP tool to run raw ClickHouse SQL via SigNoz /api/v3/query_range.
  • Support time-range templating in SQL (start/end timestamps and datetimes).
  • Default to last 1 day when no explicit time range is provided.

Problem

The existing MCP tools expose high-level query builder and aggregation flows, but do not support arbitrary ClickHouse SQL. For complex analyses, schema exploration, or existing SQL workflows, users must leave their MCP client and run queries elsewhere, breaking the AI-assisted workflow and limiting advanced use cases.

Solution

  • Add a new MCP tool signoz_execute_clickhouse_query that:
    • Accepts a raw ClickHouse SQL string and executes it via /api/v3/query_range.
    • Supports templated time variables:
      • {{.start_timestamp}}, {{.end_timestamp}} (Unix seconds)
      • {{.start_datetime}}, {{.end_datetime}} (UTC datetime strings)
    • Resolves time from timeRange or explicit start / end, and defaults to last 1 day if none are provided.
  • Wire the tool into the MCP server and SigNoz client, and add tests for the new client method.

Test plan

  • Verified the client method calls /api/v3/query_range with the expected payload.
  • Verified signoz_execute_clickhouse_query is registered and callable from MCP clients.
  • Verified templating for {{.start_timestamp}} / {{.end_timestamp}} and datetime variants across different timeRange values.
  • Verified behavior when no time range is supplied (defaults to last 1 day).
  • Re-ran existing tools (metrics/logs/traces/query builder) to confirm no regressions.

@nilaydown nilaydown changed the title feat: add signoz_execute_clickhouse_query MCP tool via v3 API feat: add signoz_execute_clickhouse_query MCP tool via v3 API Mar 3, 2026
@nilaydown
Copy link
Copy Markdown
Author

nilaydown commented Mar 9, 2026

Hi! This PR adds the ClickHouse SQL v3 query tool.
The GitHub Actions workflow is waiting for maintainer approval.

Could someone please approve the workflow and take a look when convenient? Thanks!
@therealpandey @pradeepitm12 are you the right reviewers for this?

@pradeepitm12 pradeepitm12 added the safe-to-test Add this label to run CI. label Mar 9, 2026
@nilaydown
Copy link
Copy Markdown
Author

@pradeepitm12 thanks for the workflow approval! Could you review the PR as well?
Thanks

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

safe-to-test Add this label to run CI.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants