setup

name	setup
description	Guides users through setting up the ClickHouse MCP server connection bundled with this plugin. Use when the user first installs the plugin or has trouble connecting to ClickHouse.
disable-model-invocation	true

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.