Set up ClickHouse MCP server with Claude Desktop

This guide explains how to set up Claude Desktop with a ClickHouse MCP server.

Using ClickHouse MCP server with Claude Desktop

This guide explains how to set up Claude Desktop with a ClickHouse MCP server using uv and connect it to the ClickHouse example datasets.

1. Install uv

   You will need to install uv to follow the instructions in this guide. If you don’t want to use uv, you will need to update the MCP server config to use an alternative package manager.

2. Download Claude Desktop

   You’ll also need to install the Claude Desktop app, which you can download from the Claude Desktop website.

3. Configuring ClickHouse MCP server

   Once you’ve got Claude Desktop installed, it’s time to configure the ClickHouse MCP server. We can do this via the Claude Desktop configuration file.

   To find this file, first go to the settings page (Cmd+, on a Mac) and then click on the Developer tab on the left menu. You’ll then see the following screen, on which you’ll need to click on the Edit config button:

   This will take you to a directory containing the configuration file (claude_desktop_config.json). The first time you open that file, it will likely contain the following content:

   {
     "mcpServers": {}
   }
   

   The mcpServers dictionary takes in the name of an MCP server as a key, and a dictionary of configuration options as a value.
   For example, the ClickHouse MCP server configuration connecting to the ClickHouse Playground would look like this:

   {
     "mcpServers": {
       "mcp-clickhouse": {
         "command": "uv",
         "args": [
           "run",
           "--with",
           "mcp-clickhouse",
           "--python",
           "3.10",
           "mcp-clickhouse"
         ],
         "env": {
           "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
           "CLICKHOUSE_PORT": "8443",
           "CLICKHOUSE_USER": "demo",
           "CLICKHOUSE_PASSWORD": "",
           "CLICKHOUSE_SECURE": "true",
           "CLICKHOUSE_VERIFY": "true",
           "CLICKHOUSE_CONNECT_TIMEOUT": "30",
           "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
         }
       }
     }
   }
   

   Once you’ve updated the config, you’ll need to restart Claude Desktop for the changes to take effect.

   Depending on how you installed uv, you might receive the following error when restarting Claude Desktop:

   MCP mcp-clickhouse: spawn uv ENOENT
   

   If that happens, you’ll need to update the command to have the full path to uv. e.g. if you’ve installed via Cargo, it will be /Users/<username>/.cargo/bin/uv

4. Using ClickHouse MCP server

   Once you’ve restarted Claude Desktop, you can find the ClickHouse MCP server by clicking on the Search and tools icon:

   
   

   You can then choose whether to disable all or some of the tools.

   Now we’re ready to ask Claude some questions that will result in it using the ClickHouse MCP server. For example, we could ask it What's the most interesting dataset in the SQL playground?.

   Claude will ask us to confirm the use of each tool in the MCP server the first time that it’s called:

   Below you can see part of a conversation that includes some tool calls to the ClickHouse MCP server: