Skip to main content
Skip to main content
Edit this page

Enable and connect ClickHouse Cloud remote MCP server

This guide shows you how to enable the ClickHouse Cloud Remote MCP Server and set it up for use with common developer tools.

Prerequisites

Enable remote MCP server for Cloud​

Connect to the ClickHouse Cloud service for which you want to enable remote MCP server, click on the Connect button in the left hand menu. A box with connection details will open.

Select "Connect with MCP":

Toggle the button on to enable MCP for the service:

Copy the displayed URL, which is the same as the one below:

https://mcp.clickhouse.cloud/mcp

Setup remote MCP for development​

Choose your IDE or tool below and follow the corresponding setup instructions.

Claude Code​

From your working directory, run the following command to add the ClickHouse Cloud MCP Server configuration to Claude Code:

claude mcp add --transport http clickhouse-cloud https://mcp.clickhouse.cloud/mcp

Then launch Claude Code:

claude

Run the following command to list MCP servers:

/mcp

Select clickhouse-cloud and authenticate via OAuth using your credentials for ClickHouse Cloud.

Claude web UI​

  1. Navigate to Customize > Connectors
  2. Click the "+" icon and Add custom connector
  3. Give the custom connector a name like clickhouse-cloud and add it
  4. Click the newly added clickhouse-cloud connector and click Connect
  5. Authenticate using your ClickHouse Cloud credentials via OAuth

Cursor​

  1. Browse and install MCP servers from the Cursor Marketplace.
  2. Search for ClickHouse and click "Add to Cursor" on any server to install it
  3. Authenticate with OAuth.

Visual Studio Code​

Add the following configuration to your .vscode/mcp.json:

{
  "servers": {
    "clickhouse-cloud": {
      "type": "http",
      "url": "https://mcp.clickhouse.cloud/mcp"
    }
  }
}

For more details refer to the Visual Studio Code docs

Windsurf​

Edit your mcp_config.json file with the following config:

{
  "mcpServers": {
    "clickhouse-cloud": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.clickhouse.cloud/mcp"]
    }
  }
}

For more details refer to the Windsurf docs

Zed​

Add ClickHouse as a custom server. Add the following to your Zed settings under context_servers:

{
  "context_servers": {
    "clickhouse-cloud": {
      "url": "https://mcp.clickhouse.cloud/mcp"
    }
  }
}

Zed should then prompt you to authenticate via OAuth when it first connects to the server. For more details refer to the Zed docs

Codex​

Run the following command to add the ClickHouse Cloud MCP server via the CLI:

codex mcp add clickhouse-cloud --url https://mcp.clickhouse.cloud/mcp

Example usage​

Once connected, you can interact with ClickHouse Cloud through natural-language prompts. Below are some common workflows and the tools your MCP client will invoke behind the scenes. For a full list of available tools, see the tool reference.

Exploring your data​

Start by discovering what's available:

PromptTool invoked
"What organizations do I have access to?"get_organizations
"What databases are available on my service?"list_databases
"Show me the tables in the default database"list_tables
"List all tables whose names start with events_"list_tables (with the like filter)

Running analytical queries​

Ask questions in plain language and the agent will translate them into SQL:

PromptTool invoked
"Show me the top 10 rows from the hits table"run_select_query
"What's the average session duration by country for the last 7 days?"run_select_query
"How many rows are in each table in the analytics database?"run_select_query

The run_select_query tool only permits SELECT statements. All queries are read-only.

Managing services and infrastructure​

Get visibility into your ClickHouse Cloud resources:

PromptTool invoked
"List all my services"get_services_list
"What's the status of my production service?"get_service_details
"Show me the backup schedule for this service"get_service_backup_configuration
"List recent backups"list_service_backups
"What ClickPipes are configured on this service?"list_clickpipes

Monitoring costs​

PromptTool invoked
"What was my organization's cost last week?"get_organization_cost
"Show me daily costs from March 1 to March 15"get_organization_cost (with from_date and to_date)

Related content​