Summary
This server connects Claude to ClickHouse with a focus on query optimization and pipeline monitoring rather than just raw query execution. It exposes tools like ch_explain_query for EXPLAIN-based analysis with optimization suggestions, ch_pipeline_latency for CDC pipeline performance tracking, and ch_data_quality for null and duplicate detection. All operations are read-only with validation that blocks DDL, DML, and multi-statement queries. You'd reach for this when you need Claude to help diagnose slow queries, analyze data quality issues, or optimize ClickHouse table schemas. It includes built-in safeguards like 30-second timeouts and system table allowlists, making it safer for production database analysis.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
Tools
Public tool metadata for what this MCP can expose to an agent.
13 tools
get_clickpipeReturns the specified ClickPipe.3 params
Returns the specified ClickPipe.
Parameters* required
serviceIdstringID of the service that owns the ClickPipe
clickPipeIdstringID of the requested ClickPipe
organizationIdstringID of the organization that owns the service
get_organizationsRetrieves all accessible ClickHouse Cloud organizations.
Retrieves all accessible ClickHouse Cloud organizations.
No parameter schema in public metadata yet.
run_select_queryExecutes a SELECT query against a ClickHouse service. Runs a read-only SELECT query on the specified ClickHouse service via the Query API endpoint. This function provides direct access to database content through SQL queries while ensuring that only read operations are permitted.3 params
Executes a SELECT query against a ClickHouse service. Runs a read-only SELECT query on the specified ClickHouse service via the Query API endpoint. This function provides direct access to database content through SQL queries while ensuring that only read operations are permitted.
Parameters* required
querystringA valid ClickHouse SQL SELECT query string
serviceIdstringThe unique identifier of the ClickHouse service
timeoutSecondsintegerMaximum time in seconds to wait for the query to complete. Defaults to 300 (5 minutes), maximum is 3600 (1 hour). Use lower values for simple queries and higher values for complex analytical queries.
list_databasesRetrieves all databases available in a ClickHouse service.1 params
Retrieves all databases available in a ClickHouse service.
Parameters* required
serviceIdstringlist_tablesRetrieves a comprehensive list of tables in a ClickHouse database, including columns.4 params
Retrieves a comprehensive list of tables in a ClickHouse database, including columns.
Parameters* required
likestringOptional SQL LIKE pattern to filter tables by name (e.g., "events_%")
notLikestringOptional SQL LIKE pattern to exclude tables by name
databasestringName of the database to list tables from
serviceIdstringThe unique identifier of the ClickHouse service
get_services_listRetrieves all services in a ClickHouse Cloud organization.1 params
Retrieves all services in a ClickHouse Cloud organization.
Parameters* required
organizationIdstringID of the organization whose services are to be listed
get_organization_detailsReturns details of a single organization. The auth key must belong to the organization.1 params
Returns details of a single organization. The auth key must belong to the organization.
Parameters* required
organizationIdstringID of the organization to retrieve
get_service_detailsReturns a service that belongs to the organization.2 params
Returns a service that belongs to the organization.
Parameters* required
serviceIdstringID of the service to retrieve
organizationIdstringID of the organization
list_clickpipesRetrieves all ClickPipes configured for a specific service.2 params
Retrieves all ClickPipes configured for a specific service.
Parameters* required
serviceIdstringID of the service to list ClickPipes for
organizationIdstringID of the organization
list_service_backupsReturns a list of all backups for the service. The most recent backups comes first in the list.2 params
Returns a list of all backups for the service. The most recent backups comes first in the list.
Parameters* required
serviceIdstringID of the service to list backups for
organizationIdstringID of the organization
get_organization_costRetrieves billing and usage cost data for a ClickHouse Cloud organization. Returns a grand total and a list of daily, per-entity organization usage cost records for the organization in the queried time period (maximum 31 days).3 params
Retrieves billing and usage cost data for a ClickHouse Cloud organization. Returns a grand total and a list of daily, per-entity organization usage cost records for the organization in the queried time period (maximum 31 days).
Parameters* required
to_datestringEnd date (inclusive) for the report, e.g. 2024-12-20 (YYYY-MM-DD). Cannot be more than 30 days after from_date.
from_datestringStart date for the report, e.g. 2024-12-19 (YYYY-MM-DD)
organizationIdstringThe unique identifier of the organization
get_service_backup_detailsReturns a single backup info.3 params
Returns a single backup info.
Parameters* required
backupIdstringID of the backup
serviceIdstringID of the service
organizationIdstringID of the organization that owns the service
get_service_backup_configurationReturns the service backup configuration.2 params
Returns the service backup configuration.
Parameters* required
serviceIdstringID of the service
organizationIdstringID of the organization that owns the service
clickhouse-dataops-mcp
mcp-name: io.github.Aguantar/clickhouse-dataops-mcp
A DataOps-focused MCP server for ClickHouse with query optimization, pipeline latency analysis, and data quality monitoring.
Features
Unlike generic ClickHouse MCP servers that only run queries, this server acts as a query optimization advisor:
ch_query— Execute SELECT with automatic partition pruning warningsch_explain_query— EXPLAIN-based analysis with optimization suggestionsch_table_schema— Comprehensive table metadata (columns, keys, partitions, samples)ch_pipeline_latency— CDC pipeline per-segment latency (p50/p95/p99)ch_data_quality— Null/duplicate/gap detection with market coverage checksch_slow_queries— Slow query detection with root cause diagnosisch_disk_usage— Disk analysis with TTL and optimization recommendationsch_list_tables— Table catalog with built-in descriptions
Safety
All queries are read-only. DDL/DML operations are blocked at the SQL validation layer:
- Blocked:
DROP,TRUNCATE,DELETE,ALTER,INSERT,UPDATE,CREATE, etc. - Multi-statement queries blocked (
;separator) - Comment-based bypass prevented (comments stripped before validation)
- System tables restricted to allowlist
- Query timeout: 30 seconds
- Row limit enforcement
Installation
pip install clickhouse-dataops-mcp
Usage with Claude Code
Add to your .mcp.json:
{
"mcpServers": {
"clickhouse": {
"command": "clickhouse-mcp-server",
"env": {
"CLICKHOUSE_HOST": "localhost",
"CLICKHOUSE_PORT": "8123",
"CLICKHOUSE_DATABASE": "cdc_pipeline"
}
}
}
}
Environment Variables
| Variable | Default | Description |
|---|---|---|
CLICKHOUSE_HOST | localhost | ClickHouse HTTP host |
CLICKHOUSE_PORT | 8123 | ClickHouse HTTP port |
CLICKHOUSE_USER | default | ClickHouse username |
CLICKHOUSE_PASSWORD | (empty) | ClickHouse password |
CLICKHOUSE_DATABASE | cdc_pipeline | Default database |
CLICKHOUSE_QUERY_TIMEOUT | 30 | Query timeout in seconds |
License
MIT
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →Configuration
CLICKHOUSE_HOSTClickHouse HTTP host
CLICKHOUSE_PORTClickHouse HTTP port
CLICKHOUSE_PASSWORDsecretClickHouse password
Registryactive
Packageclickhouse-dataops-mcp
TransportSTDIO
AuthRequired
UpdatedMar 19, 2026
