ClickHouse MCP server for AI agents

The ClickHouse MCP Server enables Claude to interact with ClickHouse databases through SQL queries, providing a bridge between the AI assistant and your data. It supports both remote ClickHouse instances and the embedded chDB engine.

Installation and Configuration

Basic Configuration

To set up the ClickHouse MCP Server for Claude Desktop:

Locate the Claude Desktop configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%/Claude/claude_desktop_config.json
Add the following configuration for a ClickHouse connection:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Using ClickHouse SQL Playground

To try it out with a public demo instance:

{
  "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"
      }
    }
  }
}

Using chDB (Embedded ClickHouse)

To use the embedded chDB engine:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CHDB_ENABLED": "true",
        "CLICKHOUSE_ENABLED": "false",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

Using Both ClickHouse and chDB

You can enable both simultaneously:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30",
        "CHDB_ENABLED": "true",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

Installation Without uv (Using System Python)

If you prefer not to use uv:

Install the package:

python3 -m pip install mcp-clickhouse

Update your Claude Desktop configuration:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "python3",
      "args": [
        "-m",
        "mcp_clickhouse.main"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Alternatively, use the installed script directly:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "mcp-clickhouse",
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Available Tools

ClickHouse Tools

run_select_query: Execute SQL queries on your ClickHouse cluster (read-only).
- Input: sql (string) - The SQL query to execute.
list_databases: List all databases on your ClickHouse cluster.
list_tables: List all tables in a specific database.
- Input: database (string) - The name of the database.

chDB Tools

run_chdb_select_query: Execute SQL queries using chDB's embedded ClickHouse engine.
- Input: sql (string) - The SQL query to execute.
- This allows querying data from files, URLs, and databases without ETL processes.

Configuration Options

ClickHouse Variables

Required Variables

CLICKHOUSE_HOST: ClickHouse server hostname
CLICKHOUSE_USER: Username for authentication
CLICKHOUSE_PASSWORD: Password for authentication

Optional Variables

CLICKHOUSE_PORT: Default is 8443 for HTTPS, 8123 for HTTP
CLICKHOUSE_SECURE: Enable/disable HTTPS ("true" by default)
CLICKHOUSE_VERIFY: Enable/disable SSL verification ("true" by default)
CLICKHOUSE_CONNECT_TIMEOUT: Connection timeout in seconds ("30" by default)
CLICKHOUSE_SEND_RECEIVE_TIMEOUT: Query timeout in seconds ("300" by default)
CLICKHOUSE_DATABASE: Default database to use
CLICKHOUSE_MCP_SERVER_TRANSPORT: Transport method ("stdio", "http", or "sse")
CLICKHOUSE_MCP_BIND_HOST: Host to bind for HTTP/SSE ("127.0.0.1" by default)
CLICKHOUSE_MCP_BIND_PORT: Port for HTTP/SSE ("8000" by default)
CLICKHOUSE_MCP_QUERY_TIMEOUT: Timeout for SELECT tools ("30" by default)
CLICKHOUSE_ENABLED: Enable/disable ClickHouse functionality ("true" by default)

chDB Variables

CHDB_ENABLED: Enable/disable chDB functionality ("false" by default)
CHDB_DATA_PATH: Path to chDB data directory (":memory:" by default)

Health Check

When running with HTTP or SSE transport, a health check endpoint is available at /health, which:

Returns 200 OK with the ClickHouse version if healthy
Returns 503 Service Unavailable if unable to connect

Example:

curl http://localhost:8000/health
# Response: OK - Connected to ClickHouse 24.3.1

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "mcp-clickhouse" '{"command":"uv","args":["run","--with","mcp-clickhouse","--python","3.13","mcp-clickhouse"],"env":{"CLICKHOUSE_HOST":"<clickhouse-host>","CLICKHOUSE_PORT":"<clickhouse-port>","CLICKHOUSE_USER":"<clickhouse-user>","CLICKHOUSE_PASSWORD":"<clickhouse-password>","CLICKHOUSE_SECURE":"true","CLICKHOUSE_VERIFY":"true","CLICKHOUSE_CONNECT_TIMEOUT":"30","CLICKHOUSE_SEND_RECEIVE_TIMEOUT":"30"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "mcp-clickhouse": {
            "command": "uv",
            "args": [
                "run",
                "--with",
                "mcp-clickhouse",
                "--python",
                "3.13",
                "mcp-clickhouse"
            ],
            "env": {
                "CLICKHOUSE_HOST": "<clickhouse-host>",
                "CLICKHOUSE_PORT": "<clickhouse-port>",
                "CLICKHOUSE_USER": "<clickhouse-user>",
                "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
                "CLICKHOUSE_SECURE": "true",
                "CLICKHOUSE_VERIFY": "true",
                "CLICKHOUSE_CONNECT_TIMEOUT": "30",
                "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "mcp-clickhouse": {
            "command": "uv",
            "args": [
                "run",
                "--with",
                "mcp-clickhouse",
                "--python",
                "3.13",
                "mcp-clickhouse"
            ],
            "env": {
                "CLICKHOUSE_HOST": "<clickhouse-host>",
                "CLICKHOUSE_PORT": "<clickhouse-port>",
                "CLICKHOUSE_USER": "<clickhouse-user>",
                "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
                "CLICKHOUSE_SECURE": "true",
                "CLICKHOUSE_VERIFY": "true",
                "CLICKHOUSE_CONNECT_TIMEOUT": "30",
                "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect