How to connect ClickHouse MCP to Claude Cowork

Connect Claude Cowork to ClickHouse MCP. List top 10 slow queries last hour, aggregate error rates by service today, and more using natural language, with authentication handled for you.

ClickHouse MCP logoClickHouse MCP
Dcr Oauth

ClickHouse MCP is ClickHouse Cloud's managed observability query service via the ClickStack MCP server. Use it to run fast analytical queries against observability data with managed access.

32 Tools

Introduction

Cowork is Anthropic's AI agent for knowledge work. Think of it as Claude Code for everything else. It works autonomously with your computer, local files, and applications to accomplish complex tasks.

This guide walks you through the easiest and most secure way to connect your ClickHouse account to Cowork via Composio Connect, enabling it to list top 10 slow queries last hour, aggregate error rates by service today, create materialized view for cpu metrics, and more such actions on your behalf without compromising your account security.

Also integrate ClickHouse MCP with

Connecting ClickHouse to Claude Cowork

1. Open Customize

In Claude Desktop, click Customize in the left sidebar, then select Connectors and click the + icon at the top.

Claude Desktop connectors screen with Add custom connector selected

2. Add the Composio MCP server

Click Add custom connector and paste in the Composio MCP server URL:

bash
https://connect.composio.dev/mcp
Add custom connector dialog with Composio MCP server URL

3. Authorize in your browser

Click Connect. You'll be redirected to a browser window where you can authorize Composio to continue.

Composio authorization screen for Claude Cowork

4. Connect your ClickHouse account

Back in Cowork, ask the agent to connect to ClickHouse or give it any ClickHouse-related task.

For example, ask Cowork to:

  • "List top 10 slow queries last hour"
  • "Aggregate error rates by service today"
  • "Create materialized view for cpu metrics"

It will prompt you to authenticate and authorize access.

That's it. Composio's tools are now available in Cowork, and your ClickHouse account is ready to use.

What is Claude Cowork?

Claude Cowork is Anthropic's agent for general knowledge work. It can use your computer, files, and connected applications to complete longer-running tasks across your work tools.

With Composio Connect, Cowork can securely access apps like ClickHouse through MCP without you sharing account credentials directly with the agent.

What is the ClickHouse MCP server, and what's possible with it?

The ClickHouse MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your ClickHouse account. It provides structured and secure access so your agent can perform ClickHouse operations on your behalf.

TOOLS

Supported Tools

Every ClickHouse MCP action and event your agent gets out of the box.

Clickstack delete dashboard

Permanently delete a dashboard by ID.

Clickstack delete source

Permanently delete a data source by ID.

Clickstack delete webhook

Permanently delete a webhook by ID.

Clickstack describe metric

DRILL-DOWN: Use after clickstack_list_metrics (or after a clickstack_describe_source sample) to get attribute keys, sampled values, unit, and description for a specific (metricName, kind) pair.

Clickstack describe source

CALL THIS BEFORE WRITING QUERIES — prevents unknown-column errors.

Clickstack emerging signals

Detect what is NEW or GONE between an earlier baseline window and a current window — log/event patterns that emerged, ramped up, or stopped.

Clickstack event deltas

Rank the properties of two row groups (logs or trace spans) by how much their value distributions differ.

Clickstack event patterns

Discover the most common log messages and event patterns.

Clickstack get alert

Without an ID: list all alerts as a high-level summary (id, name, state, source, interval).

Clickstack get dashboard

Without an ID: list all dashboards (returns IDs, names, tags).

Clickstack get dashboard tile

Retrieve a single tile from a dashboard by tileId.

Clickstack get saved search

Without an ID: list all saved searches as a high-level summary (id, name, tags).

Clickstack get source filter values

List the available values for the required source filter columns on a single source.

Clickstack get webhook

List available webhook destinations (id, name, service type).

Clickstack list metrics

DISCOVERY: Use this after clickstack_describe_source when you need more metric names than the per-kind sample shows, or when you want to narrow by kind / name pattern / time window.

Clickstack list sources

List all data sources (logs, metrics, traces) and database connections available to this team.

Clickstack list teams

List all teams the current user belongs to and identify which team is active for this session.

Clickstack patch dashboard

Make targeted updates to a dashboard without resubmitting the full object.

Clickstack query tile

Execute the query for a specific tile on an existing dashboard.

Clickstack query tiles

Run the queries for many tiles of a dashboard in ONE call and return a compact per-tile success/failure summary.

Clickstack save alert

Create a new alert (omit id) or update an existing one (provide id).

Clickstack save dashboard

Create a new dashboard (omit id) or update an existing one (provide id).

Clickstack save saved search

Create a new saved search (omit id) or update an existing one (provide id).

Clickstack save source

Create a new data source (omit id) or update an existing one (provide id) so shipped telemetry becomes queryable.

Clickstack save webhook

Create a new webhook (omit id) or update an existing one (provide id).

Clickstack search

Browse individual log/event/trace rows.

Clickstack search dashboards

Search dashboards by name and/or tags.

Clickstack sql

Execute raw ClickHouse SQL.

Clickstack table

Compute aggregated metrics as a table, single number, pie chart, or bar chart.

Clickstack timeseries

Plot metrics over time as a line or stacked bar chart.

Clickstack trace top time consuming operations

Given a parent-span filter and a time window, return the child operations contributing the most cumulative time across all traces matching the parent filter.

Clickstack trace waterfall

Fetch all spans in ONE trace and return them as a parent/child waterfall, pre-ordered for human-readable display.

FRAMEWORKS

How to build ClickHouse MCP Agent with another framework

FAQ

Frequently asked questions

With a standalone ClickHouse MCP server, the agents and LLMs can only access a fixed set of ClickHouse tools tied to that server. However, with the Composio Tool Router, agents can dynamically load tools from ClickHouse and many other apps based on the task at hand, all through a single MCP endpoint.

Yes, you can. Claude Cowork fully supports MCP integration. You get structured tool calling, message history handling, and model orchestration while Tool Router takes care of discovering and serving the right ClickHouse tools.

Yes, absolutely. You can configure which ClickHouse scopes and actions are allowed when connecting your account to Composio. You can also bring your own OAuth credentials or API configuration so you keep full control over what the agent can do.

All sensitive data such as tokens, keys, and configuration is fully encrypted at rest and in transit. Composio is SOC 2 Type 2 compliant and follows strict security practices so your ClickHouse data and credentials are handled as safely as possible.

Start with ClickHouse MCP.It takes 30 seconds.

Managed auth, hosted MCP servers, and every ClickHouse MCP tool your agent needs.Free to start.

Start building