Connecting AI agents to ClickHouse v26.3

Connect an AI agent to your ClickHouse server with edb-clickhouse-mcp to list databases, describe schemas, and run queries in response to plain-language questions instead of requiring hand-written SQL.

edb-clickhouse-mcp is EDB's packaging of the open-source ClickHouse MCP server for Model Context Protocol (MCP), an open standard that lets AI agents call external tools over a common interface. EDB provides RPM and container packaging, and a set of opt-in diagnostic tools covered in Understanding the available tools.

Understanding the integration

Three separate pieces come together to answer a natural-language question against ClickHouse, and each one can run on its own machine and its own platform:

• AI client: Claude Desktop, Claude Code, Cursor, or another MCP-compatible client, running on macOS, Windows, or Linux. Configure it in the client's own configuration file, covered in Connecting an AI client.
• edb-clickhouse-mcp: the RPM on a RHEL-compatible Linux host, or the container image on macOS, Windows, or Linux. Configure it in mcp.env for the RPM, or with environment variables for the container, covered in Configuration parameters.
• ClickHouse server: wherever your ClickHouse cluster or node already runs, in Docker, on Linux, or on Kubernetes. Set it up as described in Installing and upgrading.

Setup workflow

Work through these steps in order:

1. Install edb-clickhouse-mcp as an RPM package or a container image, on whichever machine you want it to run, not necessarily the same one as your ClickHouse server.
2. Edit edb-clickhouse-mcp's configuration to point it at your ClickHouse server and give it credentials to authenticate.
3. Review the available tools it registers, and turn on the EDB diagnostic tools if you want them.
4. Connect your AI client to edb-clickhouse-mcp.
5. Ask it a question in natural language.

Installing edb-clickhouse-mcp

Install edb-clickhouse-mcp as an RPM package or a container image, both available for x86_64 and aarch64. Install it on whichever machine you want the MCP server to run on, as long as it can reach your ClickHouse node over the network. edb-clickhouse-mcp connects to a single ClickHouse endpoint, not a cluster as a whole, as described in Configuration parameters.

Installing the RPM package

This package requires a RHEL-compatible Linux host.

1. Set up the EDB repository and install the package, using the same clickhouse subscription plan as the ClickHouse server and client packages:

   → WrapCopy

   export EDB_SUBSCRIPTION_TOKEN=<your-token>
   export EDB_SUBSCRIPTION_PLAN=clickhouse
   curl -1sSLf "https://downloads.enterprisedb.com/$EDB_SUBSCRIPTION_TOKEN/$EDB_SUBSCRIPTION_PLAN/setup.rpm.sh" | sudo -E bash
   sudo dnf install -y edb-clickhouse-mcp

   Replace <your-token> with the token you received when you registered for the EDB subscription. This command installs a self-contained virtual environment under /opt/edb/clickhouse-mcp, with edb-clickhouse-mcp as the only command added to PATH, and connection settings in /etc/edb-clickhouse-mcp/mcp.env.

2. Point it at your ClickHouse node. Edit /etc/edb-clickhouse-mcp/mcp.env and set at least CLICKHOUSE_HOST, CLICKHOUSE_USER, and CLICKHOUSE_PASSWORD, described in Configuration parameters.

Installing the container image

This image runs on macOS, Windows, or Linux, through Docker or Podman.

1. Log in to the EDB container registry and pull the image, using the same clickhouse repository as the ClickHouse server image:

   → WrapCopy

   export EDB_SUBSCRIPTION_TOKEN=<your-token>
   echo "$EDB_SUBSCRIPTION_TOKEN" | docker login docker.enterprisedb.com \
     --username clickhouse \
     --password-stdin
   docker pull docker.enterprisedb.com/clickhouse/edb-clickhouse-mcp:0.4.1-1edb1

   Replace <your-token> with the token you received when you registered for the EDB subscription.

2. Run it:

   → WrapCopy

   docker run --rm -i \
     -e CLICKHOUSE_HOST=<clickhouse-host> \
     -e CLICKHOUSE_USER=<clickhouse-user> \
     -e CLICKHOUSE_PASSWORD=<clickhouse-password> \
     docker.enterprisedb.com/clickhouse/edb-clickhouse-mcp:0.4.1-1edb1

   Where <clickhouse-host>, <clickhouse-user>, and <clickhouse-password> are your ClickHouse connection details, described in Configuration parameters.

Configuration parameters

These parameters configure the connection to your ClickHouse server, set either in /etc/edb-clickhouse-mcp/mcp.env for the RPM or passed directly to the container:

Secret values, such as CLICKHOUSE_PASSWORD, and common key=value secret patterns are redacted from every tool's output and error messages before they reach the client or the logs.

Understanding the available tools

Review the tools edb-clickhouse-mcp registers before connecting your AI client, so you know what an agent can do once it's connected. When a client connects, it discovers the names and descriptions of the tools already registered, and the AI model behind it uses that information to decide when to call each one.

Default tools

These four tools register by default, regardless of whether the server is installed from the RPM or the container image:

EDB diagnostic tools

Set EDB_MCP_ENABLED=true, either in /etc/edb-clickhouse-mcp/mcp.env for the RPM or passed directly to the container, to register four additional read-only tools that give an agent operational visibility into the server beyond running queries:

Tuning the diagnostic tools

Set these variables the same way as the connection settings, either in mcp.env for the RPM or passed directly to the container. Restart edb-clickhouse-mcp to apply changes, as described in Configuration parameters.

Connecting an AI client

Connect your AI client to edb-clickhouse-mcp so it can call the tools registered on it. Where the client runs relative to edb-clickhouse-mcp, same machine or different, determines the transport, client configuration, and authentication, as shown here:

Setting up the remote server

If edb-clickhouse-mcp runs on a different machine than your AI client, configure it for network access first, then pick Connect to a remote server in Editing the Claude Desktop configuration. If it runs on the same machine as the client, skip this section.

Set the following, either in /etc/edb-clickhouse-mcp/mcp.env for the RPM or passed directly to the container:

1. Set CLICKHOUSE_MCP_SERVER_TRANSPORT to http or sse, and CLICKHOUSE_MCP_BIND_HOST=0.0.0.0. CLICKHOUSE_MCP_BIND_HOST otherwise defaults to 127.0.0.1 and only accepts connections from the same host.

2. Set up authentication. Startup fails without it, for both transports. Pick one mode:

   Mode	Setting	When to use
   Static bearer token	CLICKHOUSE_MCP_AUTH_TOKEN	Simple or internal deployments. Generate a token with uuidgen or openssl rand -hex 32.
   OAuth / OpenID Connect (OIDC)	FASTMCP_SERVER_AUTH plus provider-specific FASTMCP_SERVER_AUTH_* variables	Production deployments behind Azure Entra, Google, GitHub, WorkOS, or another FastMCP-supported provider.
   Disabled	CLICKHOUSE_MCP_AUTH_DISABLED=true	Local development only. Avoid disabling authentication on a server reachable over a network.

3. Start edb-clickhouse-mcp. For the RPM, start the packaged systemd service:

   → WrapCopy

   sudo systemctl enable --now edb-clickhouse-mcp

   For the container, pass the settings from the previous two steps as -e flags, map the bind port, and run it detached:

   → WrapCopy

   docker run -d \
     -p 8000:8000 \
     -e CLICKHOUSE_MCP_SERVER_TRANSPORT=http \
     -e CLICKHOUSE_MCP_BIND_HOST=0.0.0.0 \
     -e CLICKHOUSE_MCP_AUTH_TOKEN=<token> \
     -e CLICKHOUSE_HOST=<clickhouse-host> \
     -e CLICKHOUSE_USER=<clickhouse-user> \
     -e CLICKHOUSE_PASSWORD=<clickhouse-password> \
     docker.enterprisedb.com/clickhouse/edb-clickhouse-mcp:0.4.1-1edb1

4. Also open the corresponding inbound rule for the bind port, such as an EC2 security group or other cloud firewall rule, or your network firewall otherwise.

5. Check the unauthenticated /health endpoint, which reports server and connectivity status for load balancers and orchestrator probes:

   → WrapCopy

   curl http://<mcp-host>:8000/health

   It returns 200 OK when the server can reach ClickHouse, and 503 otherwise, without version or error details in the body.

Editing the Claude Desktop configuration

The following steps use Claude Desktop as an example. Other MCP-compatible clients, such as Claude Code or Cursor, need the same configuration, added to their own configuration file instead.

1. Open Settings > Developer > Edit Config in Claude Desktop to reach claude_desktop_config.json directly:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%/Claude/claude_desktop_config.json

2. Add one of the following configurations to its mcpServers object, alongside any servers already listed there, rather than replacing the file. Pick the one that matches your setup.

   Tip

   Wherever a configuration uses "command": "docker", replace "docker" with its full path if Claude Desktop can't find it, since it doesn't always inherit your shell's PATH.

   • Point at your own ClickHouse server: launches edb-clickhouse-mcp as a subprocess on the same machine as the client, over stdio, pointed at your ClickHouse instance. This setup covers the everyday case for a laptop or workstation running both the client and the server. The command depends on how you installed edb-clickhouse-mcp:

     If you installed the RPM, on a Linux host:

     → WrapCopy

     {
       "mcpServers": {
         "clickhouse": {
           "command": "/usr/bin/edb-clickhouse-mcp",
           "env": {
             "CLICKHOUSE_HOST": "<clickhouse-host>",
             "CLICKHOUSE_USER": "<clickhouse-user>",
             "CLICKHOUSE_PASSWORD": "<clickhouse-password>"
           }
         }
       }
     }

     If you installed the Docker container image:

     → WrapCopy

     {
       "mcpServers": {
         "clickhouse": {
           "command": "docker",
           "args": [
             "run", "--rm", "-i",
             "-e", "CLICKHOUSE_HOST=<clickhouse-host>",
             "-e", "CLICKHOUSE_USER=<clickhouse-user>",
             "-e", "CLICKHOUSE_PASSWORD=<clickhouse-password>",
             "docker.enterprisedb.com/clickhouse/edb-clickhouse-mcp:0.4.1-1edb1"
           ]
         }
       }
     }

   • Try the ClickHouse SQL Playground: the same subprocess setup as pointing at your own ClickHouse server, but aimed at ClickHouse's public, read-only demo instance instead. Use this option to confirm the configuration mechanism works, with no ClickHouse instance of your own needed, before pointing it at real data.

     If you installed the RPM, on a Linux host:

     → WrapCopy

     {
       "mcpServers": {
         "clickhouse": {
           "command": "/usr/bin/edb-clickhouse-mcp",
           "env": {
             "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
             "CLICKHOUSE_PORT": "8443",
             "CLICKHOUSE_USER": "demo",
             "CLICKHOUSE_PASSWORD": ""
           }
         }
       }
     }

     If you installed the Docker container image:

     → WrapCopy

     {
       "mcpServers": {
         "clickhouse": {
           "command": "docker",
           "args": [
             "run", "--rm", "-i",
             "-e", "CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com",
             "-e", "CLICKHOUSE_PORT=8443",
             "-e", "CLICKHOUSE_USER=demo",
             "-e", "CLICKHOUSE_PASSWORD=",
             "docker.enterprisedb.com/clickhouse/edb-clickhouse-mcp:0.4.1-1edb1"
           ]
         }
       }
     }

   • Connect to a remote server: when edb-clickhouse-mcp runs on a different machine than the client, such as your ClickHouse server. Claude Desktop's mcpServers only supports launching local subprocesses, not connecting to a URL directly, so this configuration launches mcp-remote as a bridge instead, which forwards requests over the network with a bearer token. Requires the remote server setup above.

     → WrapCopy

     {
       "mcpServers": {
         "clickhouse": {
           "command": "npx",
           "args": [
             "-y",
             "mcp-remote",
             "http://<mcp-host>:8000/mcp",
             "--header",
             "Authorization: Bearer <token>"
           ]
         }
       }
     }

     Where <mcp-host> is the host running edb-clickhouse-mcp, and <token> is the value of CLICKHOUSE_MCP_AUTH_TOKEN. -y lets npx install mcp-remote without prompting, since Claude Desktop launches it with no terminal attached to answer one.

3. Restart Claude Desktop to apply the configuration.

Querying ClickHouse in natural language

Ask the AI agent a plain-language question once your client connects to edb-clickhouse-mcp:

1. When the client connects to edb-clickhouse-mcp, it fetches the full list of registered tools, along with each tool's description.
2. Ask a question, for example "What databases are on my ClickHouse server?"
3. The agent matches your question against the tool descriptions and calls the relevant one itself. For this question, that's list_databases.
4. edb-clickhouse-mcp runs the equivalent of SHOW DATABASES against your server and returns the result.
5. The agent turns that into an answer, such as "Your server has these databases: default, system, analytics." Most clients, including Claude Desktop, show somewhere in the conversation that a tool was called.