ClickHouse MCP
Manage and query ClickHouse Cloud observability data through the managed ClickStack MCP server.
Verdict
Common use cases
- Query user behavior logs during standups
- Validate data pipeline outputs before deployment
- Generate weekly KPI summaries from raw events
- Debug anomalies in time-series metrics
- Prototype SQL for dashboard widgets
Integration
- Vendor
- ClickHouse MCP
- Category
- other
- Auth
- OAUTH2
- Composio slug
clickhouse_mcp
Tools
Setup
Setup guide
- 11. Open your Switchy workspace and navigate to Settings > Integrations > ClickHouse MCP. 2. Click 'Connect ClickHouse' to start the OAuth flow. 3. You'll be redirected to authenticate with your ClickHouse instance — provide the host URL, port, database name, username, and password. 4. Grant read-only access to the tables your team needs (Switchy requests SELECT permissions only). 5. Once authorized, return to Switchy and you'll see 'ClickHouse MCP connected' with a green status indicator. 6. Test the connection by opening any Project, typing '@ClickHouse show me the schema for the events table', and hitting send — the AI should return column names and types within seconds. 7. If the response times out, check your ClickHouse instance allows external connections and your credentials have the correct database scope.
What teammates see: by default, memories from ClickHouse MCP are scoped to the Project (PROJECT visibility) - you can mark any memory PRIVATE or share it ORG-wide.
Works well with
Top models
Compatibility data appears once enough Projects have used this MCP together with a given model.
How Switchy teams use it
Starter prompts
Schema Overview
@ClickHouse list all tables in the analytics database and show me the schema for the user_events table
Daily Active Users
@ClickHouse how many distinct user_ids appeared in the events table in the last 24 hours
Top Referrers
@ClickHouse show me the top 10 referrer domains from the page_views table for the past 7 days, ordered by count
Error Rate Spike
@ClickHouse count error events by hour for the last 48 hours where status_code >= 500
Revenue by Cohort
@ClickHouse calculate total revenue grouped by user signup month from the transactions table, joined with users on user_id
Example outputs
Illustrative - representative of the model's voice and quality, not literal recordings.
@ClickHouse what's the average query response time for our analytics endpoints over the last 24 hours, broken down by hour?
Based on the query_log table, average response times ranged from 127ms (2 AM) to 843ms (11 AM peak). The 11 AM spike correlates with the daily batch job window. Median response time across all hours was 312ms. This example shows aggregated metrics from a hypothetical ClickHouse deployment — actual column names and table schemas depend on your instance configuration.
This read-heavy example demonstrates querying time-series analytics data, a core ClickHouse strength. Requires OAuth2 connection with read access to system tables or your custom analytics schema. Response speed depends on table size and indexing strategy — ClickHouse excels at columnar scans but you'll need proper partitioning for billion-row tables.
@ClickHouse insert a new event record: user_id 8472, event_type 'checkout_completed', revenue 127.50, timestamp now, session_id 'abc-xyz-123'
Inserted 1 row into the events table. The record includes user_id=8472, event_type='checkout_completed', revenue=127.50, timestamp=2025-01-15 14:32:18 UTC, session_id='abc-xyz-123'. Note this is an illustrative confirmation — actual insert behavior depends on your table schema, whether you're using a distributed table, and any materialized views that trigger on insert.
This write example shows single-row insertion, though ClickHouse is optimized for batch inserts (thousands of rows at once). Requires OAuth2 write permissions. Be cautious with high-frequency single inserts — they create many small parts that ClickHouse must later merge, potentially degrading performance. Batch your writes when possible.
@ClickHouse pull the top 10 error codes from our application logs in the past week, then draft a summary explaining which services are failing most often
Top errors: 'database_timeout' (2,847 occurrences), 'api_rate_limit' (1,203), 'auth_token_expired' (891). The payment-service accounts for 68% of database timeouts, suggesting connection pool exhaustion. The API rate limit errors cluster around the search-service during business hours. Auth token expirations are evenly distributed. This synthesis combines ClickHouse aggregation with AI interpretation — the actual error taxonomy and service names reflect your logging schema.
This synthesis example pairs ClickHouse's fast aggregation with the AI's ability to interpret patterns and draft explanations. Useful for turning raw operational data into actionable insights. Requires read access to your logs table. The AI's interpretation is only as good as the data quality — ensure your error codes and service tags are consistently logged.
Use-case deep-dives
When ClickHouse MCP fits fast-iteration analytics work
A 3-person data team at a B2B SaaS company needs to prototype dashboard queries against event logs before handing specs to engineering. ClickHouse MCP works here because OAuth2 auth means the team can connect their shared workspace without passing credentials in chat, and the columnar query speed lets them iterate on aggregations in real time during a 30-minute working session. The trade-off: if your ClickHouse instance sits behind a VPN or requires certificate-based auth, OAuth2 won't reach it and you'll need a different integration path. If your queries consistently return under 10 seconds and your data lives in a cloud-hosted ClickHouse deployment, this MCP turns Switchy into a collaborative query scratchpad.
ClickHouse MCP for support-driven event lookups
A 5-person support team at a mobile app company investigates user behavior by querying event streams when tickets escalate. ClickHouse MCP fits this workflow because OAuth2 lets support reps authenticate once per session without needing direct database credentials, and the query interface surfaces patterns across millions of events without leaving the chat context. The boundary: if your support team runs more than 20 queries per ticket, the lack of saved-query tooling in the MCP becomes friction—you'll want a BI layer instead. For teams running 3-8 investigative queries per escalation and working from a shared ClickHouse tenant, this MCP closes the loop between conversation and data.
When ClickHouse MCP speeds postmortem analysis
A 6-person engineering team runs postmortems after outages and needs to pull request-rate spikes, error distributions, and latency percentiles from ClickHouse logs. ClickHouse MCP works because OAuth2 auth keeps credentials out of the postmortem doc, and the team can collaboratively refine time-window queries in Switchy while writing the incident narrative. The limit: if your postmortem process involves joining ClickHouse data with Postgres application state or S3 trace files, the MCP won't orchestrate cross-system queries—you'll script that separately. For teams whose postmortem data lives entirely in ClickHouse and who write reports collaboratively in under 90 minutes, this MCP keeps the data pull inside the writing flow.
Frequently asked
What does the ClickHouse MCP do in Switchy?
It connects your team's Switchy workspace to ClickHouse databases, letting AI assistants query and analyze data directly through natural language. Your team can ask questions about your data without writing SQL, and the MCP translates those requests into ClickHouse queries. Results come back formatted and ready to use in conversations or workflows.
Do I need database admin rights to connect ClickHouse?
You need credentials with read access at minimum — typically a service account or OAuth2 token with SELECT permissions on the tables your team wants to query. Write access depends on whether you want the MCP to create tables or insert data. Most teams start with read-only access and expand permissions later if needed.
Can the ClickHouse MCP modify data or just read it?
That depends on the permissions you grant during OAuth2 setup. The MCP can execute whatever queries your credentials allow — reads, writes, schema changes. If you only grant SELECT permissions, it stays read-only. Most teams lock it down to queries and aggregations to avoid accidental data changes through AI conversations.
Why use this instead of ClickHouse's web console or API?
The MCP brings ClickHouse into your team's AI workspace where conversations already happen. Instead of switching to the console, writing SQL, copying results back, your team asks questions in plain English and gets answers inline. It's faster for exploratory analysis and makes data accessible to non-technical teammates who don't write SQL.
Who on the team should set up the ClickHouse connection?
Whoever manages your ClickHouse instance or has OAuth2 credentials with appropriate database permissions. Once connected, any Switchy workspace member can query through the MCP based on your team's access policies. The person connecting it controls which databases and tables become available to the AI assistants.