How to Connect ClickHouse Cloud to Gemini via MCP

💡 No install? Use cloud.anythingmcp.com directly. Sign in, click Connectors → ClickHouse Cloud, paste your credentials, mint an MCP API key and you're done. No Docker, no git clone, no local server.

ClickHouse Cloud + Gemini

Manage a ClickHouse Cloud organization from your AI agent: list services with their state, endpoints and scaling, start, stop or wake them, change IP access, tags and autoscaling, check backups and ClickPipes, read usage costs in ClickHouse Credits and the remaining credits, and look at notifications, quotas, members, roles, API keys and the audit log.

Prerequisites

See the full setup instructions baked into the connector (visible in the in-app store when you select the connector). The required environment variables for this connector are:

CLICKHOUSE_CLOUD_KEY_ID, CLICKHOUSE_CLOUD_KEY_SECRET

Step 1 — Get credentials

Setting up takes about 3 minutes. You need access to the ClickHouse Cloud console of the organization.

1. In the ClickHouse Cloud console (https://console.clickhouse.cloud) open Organization, API keys and click New API key.
2. Give it a name, an expiry, optionally an IP allow list, and the role it needs: a read-only or developer role is enough for the reads; starting, stopping, scaling and updating services needs admin or a custom role with the service manage permission.
3. Copy the Key ID into CLICKHOUSE_CLOUD_KEY_ID and the Key secret into CLICKHOUSE_CLOUD_KEY_SECRET. The secret is shown only once; if it is lost, create a new key. The API takes both as HTTP Basic auth (key id as user name, secret as password).
4. Install the connector and run clickhouse_cloud_list_organizations: it returns the organization_id every other tool needs and confirms the key.

This connector talks to the Cloud control plane (https://api.clickhouse.cloud/v1) and does not run SQL. For queries on your tables, install the ClickHouse connector, which uses a service's HTTPS interface.

What it reads:

• Organization and key: clickhouse_cloud_list_organizations, clickhouse_cloud_get_organization (private endpoints, BYOC settings) and clickhouse_cloud_whoami (the key, its organization and roles; a beta endpoint at ClickHouse).
• Services: clickhouse_cloud_list_services (optionally filtered by tags such as tag:Environment=Production) and clickhouse_cloud_get_service with state, cloud provider and region, ClickHouse version, tier, endpoints, replica memory and count, idle scaling, IP access list, release channel and tags. clickhouse_cloud_get_service_settings shows the server settings that differ from the defaults, clickhouse_cloud_get_service_metrics the current Prometheus metrics as text (filtered_metrics for the short curated list).
• Backups: clickhouse_cloud_list_backups, clickhouse_cloud_get_backup (status, start and finish, size, duration, full or incremental) and clickhouse_cloud_get_backup_configuration (backup period, retention and daily start time).
• Ingestion: clickhouse_cloud_list_clickpipes and clickhouse_cloud_get_clickpipe for ClickPipes from Kafka, S3, Postgres, MySQL and other sources. They need a key with the ClickPipes manage permission.
• Cost and health: clickhouse_cloud_get_usage_cost per day and per entity (data warehouse, service, ClickPipe) with the metrics behind it (compute, storage, backup, data transfer), clickhouse_cloud_get_credit_balances (needs the billing view permission), clickhouse_cloud_list_notifications (billing, service health, ClickPipe failures, upgrades; filter by severity, type, resource or dates) and clickhouse_cloud_list_quotas.
• People and access: clickhouse_cloud_list_members, clickhouse_cloud_list_invitations, clickhouse_cloud_list_roles, clickhouse_cloud_list_api_keys (secrets are never returned) and clickhouse_cloud_list_activities, the audit log with actor, IP address and target ids.

What it changes:

• clickhouse_cloud_change_service_state starts, stops or wakes (awake) a service. A stop shuts the compute down: data is kept and compute billing stops, but queries fail until the service is started again, so the AI asks you first.
• clickhouse_cloud_update_service renames a service, sets the release channel (slow, default or fast) and adds or removes IP access list entries and tags. Only the fields passed change; removals run before additions.
• clickhouse_cloud_update_replica_scaling changes memory per replica (min and max in GB, multiples of 4; memory limits on the Production tier only), the autoscaling mode, the replica counts, idle scaling and the idle timeout (at least 5 minutes).
• clickhouse_cloud_change_clickpipe_state starts, stops or resyncs a ClickPipe. A resync copies the source tables again, so the AI confirms it with you.
• clickhouse_cloud_create_invitation invites a person by e-mail with role ids from clickhouse_cloud_list_roles.

All 26 tools are active after installation; none is switched off. Give the key a read-only role if the AI should only look.

Data formats: every answer is {status, requestId, result} and the data is in result. Ids are UUIDs, times ISO 8601 in UTC. Costs are in ClickHouse Credits (CHC): grandTotalCHC for the period and totalCHC per record. Memory is in GB, backup size in bytes, durations in seconds. A service state passes through starting or stopping before running or stopped; idle means scaled to zero, and the next query wakes it.

Paging: clickhouse_cloud_list_organizations, clickhouse_cloud_list_api_keys and clickhouse_cloud_list_notifications take limit (up to 250) and return nextCursor when more items exist; the AI passes it as cursor until it is missing. All other lists return everything at once.

Limits: one usage cost report covers at most 31 days (to_date at most 30 days after from_date); for longer periods the AI makes several calls. The API is rate limited per key.

Common errors: 401 means a wrong key id or secret, or an expired or disabled key. 403 means the key's role lacks the permission for the call (billing, ClickPipes and service management are separate permissions), or the caller's IP is outside the key's allow list: on AnythingMCP Cloud add the server's outbound IP, self-hosted the IP of your server. 404 means a wrong organization, service or backup id. 429 means the rate limit; wait a few seconds and try again.

The connector does not run SQL, does not create or delete services, does not restore or delete backups, does not create or revoke API keys and does not remove members.

Step 2 — Install the adapter

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Step 3 — Add the connector in Gemini

Your server URL: in AnythingMCP, open MCP Servers → the server this connector is on, and copy its URL (https://cloud.anythingmcp.com/mcp/…). Use it wherever this guide shows YOUR_SERVER_ID.

Gemini CLI reads MCP servers from ~/.gemini/settings.json (on Windows %USERPROFILE%\.gemini\settings.json). Add:

{
  "mcpServers": {
    "anythingmcp": {
      "httpUrl": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. Create an MCP API key in AnythingMCP under MCP Servers → your server → API keys, and paste it in place of YOUR_MCP_API_KEY.
2. Save the file and restart gemini.
3. Run /mcp inside Gemini CLI (or gemini mcp list in your shell): anythingmcp should show as connected.
4. Start prompting: Gemini CLI can now call the ClickHouse Cloud tools.

Available tools

Example prompts

• "Which of our ClickHouse Cloud services are running right now, and which are idle or stopped?"
• "How many ClickHouse Credits did we use in October, split by service? Which day was the most expensive?"
• "Did last night's backup of the production service finish? Show its size and duration."
• "Add 203.0.113.0/24 with the description 'office' to the IP access list of the staging service."
• "Who stopped or scaled a service in the last 7 days? Show me the audit log entries."

FAQ

Where does Gemini CLI look for MCP servers? In ~/.gemini/settings.json for your user, or in .gemini/settings.json inside a project. gemini mcp list shows each server and whether it connects.

Next steps

• Connector landing page
• Connect to Claude
• Connect to ChatGPT
• Connect to Cursor
• Connect to Meta Muse
• Connect to Microsoft Copilot