setup

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

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

2. Authenticate via OAuth: The MCP server uses OAuth with your ClickHouse Cloud credentials. Follow the prompts when first connecting to authorize access.

3. Test the connection: Try listing databases or running a simple SELECT query to confirm everything works.

Troubleshooting

• Server not appearing: Run /reload-plugins to 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 LIMIT clauses 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/notLike filtering)
• 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.