| 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
-
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
/plugin to confirm the plugin is installed and enabled, then restart the Grok session 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.
MCP Tool Call Timeouts
Agent hosts cap how long a single MCP tool call may run, and that cap is typically far shorter than ClickHouse's own query timeout. The run_select_query tool accepts a timeoutSeconds parameter (default 300s, max 3600s), but the host kills the connection at its own limit regardless of this setting — raising timeoutSeconds will not make a slow query succeed.
Implications:
- Keep queries simple and fast — complex analytical queries will be cut off before they return
- 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 the host's MCP tool call 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 31 rules covering schema design, query optimization, and insert strategy. That skill activates automatically when you work with ClickHouse -- no setup needed.
