X (Twitter)LinkedInGitHubDiscordYouTube

How to integrate ClickHouse MCP with Hermes

Connect Hermes 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.

Get started for freeGet a demo
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

Hermes is a 24/7 autonomous agent that lives on your computer or server — it remembers what it learns and evolves as your usage grows.

This guide explains the easiest and most robust way to connect your ClickHouse account to Hermes. You can do this through either Composio Connect CLI or Composio Connect MCP. For personal use we recommend the CLI, but you won't go wrong with MCP either.

Also integrate ClickHouse MCP with

ChatGPT WorkClaude Cowork

What is Composio Connect?

Composio Connect is a consumer offering that lets anyone plug 1,000+ applications directly into their agent harness — including Hermes. It can:

  • Search and load tools from relevant toolkits on-demand, reducing context usage.
  • Chain multiple tools to accomplish complex workflows via a remote workbench, without excessive back-and-forth with the LLM.
  • Manage app authentication end-to-end with zero manual overhead.

Integrating ClickHouse with Hermes

Using Composio Connect CLI

1. Install the Composio CLI

Run the install script directly, or paste https://composio.dev/hermes into your Hermes chat box to have it installed for you.

bash
curl -fsSL https://composio.dev/install | bash
Hermes authenticating with Composio

2. Authenticate

Once the CLI is installed, ask Hermes to authenticate with Composio.

3. Connect to ClickHouse

Ask your agent to connect to ClickHouse, or simply request any ClickHouse-related task. Hermes will prompt you to authenticate and authorize access.

4. Done. You're all set with a new ClickHouse connection.

Using Composio Connect MCP

1. Get your MCP URL and API Key

Go to dashboard.composio.dev and copy your Connect MCP URL and API key.

Copy MCP URL and API key from Composio dashboard

2. Open the Hermes config file

bash
nano ~/.hermes/config.yaml

3. Add the Composio Connect MCP server

bash
mcp_servers:
  composio:
    url: "https://connect.composio.dev/mcp"
    headers:
      x-consumer-api-key: "YOUR_COMPOSIO_API_KEY"
    connect_timeout: 60
    timeout: 180

Save with Ctrl + O, Enter, then exit with Ctrl + X.

4. Restart your Hermes agent

Once restarted, ask your agent to connect to ClickHouse or request any ClickHouse-related task. It will prompt you to authenticate and authorize access.

5. Done!

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.

Way Forward

With ClickHouse connected, Hermes can now act on your behalf whenever it detects a relevant task or you ask it to.

From here, you can extend Hermes further:

  • Connect more apps: Calendar, Slack, Notion, Linear, and hundreds of others are available through the same Composio Connect setup. Each new integration compounds what Hermes can do for you.
  • Build workflows across tools: Once multiple apps are connected, Hermes can chain actions together — turn an email into a calendar invite, a Slack message into a Linear ticket, or a meeting note into a follow-up draft.
  • Let it learn your patterns: The more you use Hermes, the better it gets at anticipating how you'd handle recurring tasks. Give it feedback on drafts and decisions, and it will adapt.

If you run into trouble or want to share what you've built, join the community or check out the Docs for deeper configuration options.

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

ChatGPT Work logo

ChatGPT Work

Use ClickHouse MCP with ChatGPT Work

Claude Cowork logo

Claude Cowork

Use ClickHouse MCP with Claude Cowork

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. Hermes 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