Using ClickHouse MCP server with Claude Desktop

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/use-cases/AI_ML/MCP/02_claude-desktop.md)

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

Install uv

## Install uv[​](#install-uv "Direct link to Install uv")

You will need to install [uv](https://docs.astral.sh/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.

Download Claude Desktop

## Download Claude Desktop[​](#download-claude-desktop "Direct link to Download Claude Desktop")

You'll also need to install the Claude Desktop app, which you can download from the [Claude Desktop website](https://claude.ai/desktop).

Configuring ClickHouse MCP server

## Configuring ClickHouse MCP server[​](#configure-clickhouse-mcp-server "Direct link to Configuring ClickHouse MCP server")

Once you've got Claude Desktop installed, it's time to configure the [ClickHouse MCP server](https://github.com/ClickHouse/mcp-clickhouse).
We can do this via the [Claude Desktop configuration file](https://claude.ai/docs/configuration).

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.

Note

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`

Using ClickHouse MCP server

## Using ClickHouse MCP server[​](#using-clickhouse-mcp-server "Direct link to 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:

![Find MCP servers](/docs/assets/images/find-mcp-servers-fef917b74ac0c3022091d033ea6d4e9d.gif)

  

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:

- [Install uv](#install-uv)- [Download Claude Desktop](#download-claude-desktop)- [Configuring ClickHouse MCP server](#configure-clickhouse-mcp-server)- [Using ClickHouse MCP server](#using-clickhouse-mcp-server)

Was this page helpful?