Claude MarketplacesSubmit
alyiox avatar

ClickHouse

alyiox/mcp-clickhousex

Connects Claude to ClickHouse for read-only database exploration and analytics. Exposes tools to run SELECT queries with parameterized inputs, inspect metadata across databases and tables, and analyze query plans. Enforces strict no-write policies and rejects DML or DDL statements. Supports multiple connection profiles via environment variables or config file, plus snapshot mode for large result sets that exceed the interactive 1,000 row ceiling. Query results return as CSV with configurable timeouts and row limits. Useful when you need Claude to explore table structures, validate query logic, or pull analytical data from ClickHouse without risking schema changes.

GitHub stars
1
tools
13
auth
Secret needed
transport
STDIO
env var
1
last updated
Sep 20, 2026
View on GitHub

Tools

13 tools

Public tool metadata for what this MCP can expose to an agent.

get_clickpipeReturns the specified ClickPipe.3 params

Returns the specified ClickPipe.

Parameters* required
clickPipeIdstring
ID of the requested ClickPipe
organizationIdstring
ID of the organization that owns the service
serviceIdstring
ID of the service that owns the ClickPipe
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
querystring
A valid ClickHouse SQL SELECT query string
serviceIdstring
The unique identifier of the ClickHouse service
timeoutSecondsinteger
Maximum 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
serviceIdstring
list_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
databasestring
Name of the database to list tables from
likestring
Optional SQL LIKE pattern to filter tables by name (e.g., "events_%")
notLikestring
Optional SQL LIKE pattern to exclude tables by name
serviceIdstring
The 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
organizationIdstring
ID 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
organizationIdstring
ID 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
organizationIdstring
ID of the organization
serviceIdstring
ID of the service to retrieve
list_clickpipesRetrieves all ClickPipes configured for a specific service.2 params

Retrieves all ClickPipes configured for a specific service.

Parameters* required
organizationIdstring
ID of the organization
serviceIdstring
ID of the service to list ClickPipes for
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
organizationIdstring
ID of the organization
serviceIdstring
ID of the service to list backups for
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
from_datestring
Start date for the report, e.g. 2024-12-19 (YYYY-MM-DD)
organizationIdstring
The unique identifier of the organization
to_datestring
End date (inclusive) for the report, e.g. 2024-12-20 (YYYY-MM-DD). Cannot be more than 30 days after from_date.
get_service_backup_detailsReturns a single backup info.3 params

Returns a single backup info.

Parameters* required
backupIdstring
ID of the backup
organizationIdstring
ID of the organization that owns the service
serviceIdstring
ID of the service
get_service_backup_configurationReturns the service backup configuration.2 params

Returns the service backup configuration.

Parameters* required
organizationIdstring
ID of the organization that owns the service
serviceIdstring
ID of the service

Sponsors

Promote your product hereReach 125k+ visitors monthlyPromote your product hereReach 125k+ visitors monthlyAgent CaffeineSponsoredClose your lid, come back to finished workSnugSponsoredThe clipboard manager for the AI eraPromote your product hereReach 125k+ visitors monthlyWaxSponsoredBlock anything with supervision, without erasing your iPhonePromote your product hereReach 125k+ visitors monthlyknobsSponsoredSee your site on any phone, any day, in any language

Configuration

MCP_CLICKHOUSE_DSNsecret

Optional shortcut DSN for the default profile, for example http://user:password@host:8123/database. For multiple profiles, use ~/.config/mcp-clickhousex/config.json or MCP_CLICKHOUSE_PROFILES_<NAME>_DSN.

Readme

MCP ClickHouse Tool

CI PyPI Python 3.13+ License: MIT

A read-only-by-default Model Context Protocol (MCP) server for ClickHouse that provides schema discovery, read-only queries, execution-plan analysis, opt-in writes, and profile-based access to multiple servers from a single toolset deployment.

Read-only is enforced by the engine, not by SQL text matching: the query tools' clients carry ClickHouse's readonly=1, so writes, external table functions and query-level SETTINGS are refused by the server being queried. Writes live behind a separate tool that is not registered at all until a profile asks for it.

View the full README on GitHub

Details

Repository
github.com/alyiox/mcp-clickhousex
Category
Databases
Package
mcp-clickhousex
Transport
STDIO
Auth
Required
Registry
MCP registry, active

More from alyiox

Related Databases MCP servers

View all
1arpe-io avatarFastbcp Mcparpe-io/fastbcp-mcpMCP server for FastBCP — high-performance parallel database export to files and cloud1stars
2arpe-io avatarLakexpress Mcparpe-io/lakexpress-mcpMCP server for LakeXpress — automated database-to-cloud data pipeline as Parquet1stars
3bch1212 avatarQueryshieldbch1212/queryshieldSecure SQL proxy for AI agents — NL→SQL, AST safety, per-agent RLS, audit log.1stars
4boyce-io avatarBoyceboyce-io/boyceDeterministic SQL compiler for AI agents. Your agent stops guessing SQL.1stars
5gluip avatarChart Canvasgluip/chart-canvasCreate interactive visualizations and query data sources (SQLite, CSV, Parquet, JSON)1stars
6kioie avatarmemexkioie/memexLocal MCP memory for coding agents. SQLite on your machine — preferences persist across chats.1stars