ClickHouse Plugin Setup
This plugin includes the ClickHouse Cloud Remote MCP server at https://mcp.clickhouse.cloud/mcp. It provides secure, read-only access to your ClickHouse Cloud clusters.
Setup Steps
-
Verify the MCP server is connected: Check that the ClickHouse MCP server appears in your available tools. If it does, you're ready to go.
-
Authenticate via OAuth: The MCP server uses OAuth with your ClickHouse Cloud credentials. Follow the prompts when first connecting to authorize access.
-
Test the connection: Try listing databases or running a simple SELECT query to confirm everything works.
Troubleshooting
- Server not appearing: Run
/reload-pluginsto reload plugin MCP servers. - Authentication errors: Re-authenticate by following the OAuth flow when prompted.
- Connection timeouts: Verify your network can reach
https://mcp.clickhouse.cloud. The MCP server is a remote HTTP endpoint and requires internet access.
Claude Code Timeout Limitation
Claude Code enforces a 30-second timeout on all MCP tool calls. This cannot be changed by the user or the MCP server. While the run_select_query tool accepts a timeoutSeconds parameter (default 300s, max 3600s), Claude Code will kill the connection after 30 seconds regardless of this setting.
Implications:
- Keep queries simple and fast — complex analytical queries that take longer than 30 seconds will fail
- Use
LIMITclauses to bound result sets - Prefer querying materialized views or pre-aggregated tables over raw scans of large tables
- If a query times out, break it into smaller, faster queries rather than increasing
timeoutSeconds
What the MCP Server Provides
Once connected, the ClickHouse MCP server provides these tools:
Organization & Service Management
- get_organizations — list all accessible ClickHouse Cloud organizations
- get_organization_details — details of a single organization
- get_services_list — list all services in an organization
- get_service_details — details of a single service
Database Exploration
- list_databases — list all databases in a service
- list_tables — list tables in a database (supports
like/notLikefiltering) - run_select_query — execute read-only SELECT queries (⚠️ subject to 30s Claude Code timeout)
ClickPipes
- list_clickpipes — list all ClickPipes for a service
- get_clickpipe — details of a specific ClickPipe
Backups
- list_service_backups — list all backups for a service
- get_service_backup_details — details of a specific backup
- get_service_backup_configuration — backup schedule and retention settings
Billing
- get_organization_cost — billing and usage cost data (max 31-day window)
All tools are read-only. See the ClickHouse MCP docs for details.
Best Practices Skill
This plugin also includes the clickhouse-best-practices skill with 28 rules covering schema design, query optimization, and insert strategy. That skill activates automatically when you work with ClickHouse -- no setup needed.
