ClickHouse MCP Server (TypeScript)

MCP (Model Context Protocol) server for ClickHouse, built in TypeScript. This is a work based on the python package.

Features

Claude Desktop Integration

To use this MCP server with Claude Desktop, update your Claude Desktop configuration file:

Location

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

Configuration

Add the following to your configuration:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "npx",
      "args": ["@clickhouse/mcp"],
      "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"
      }
    }
  }
}

ClickHouse SQL Playground Configuration

To try it out with the ClickHouse SQL Playground, use:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "npx",
      "args": ["@clickhouse/mcp"],
      "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"
      }
    }
  }
}

Restart Claude Desktop to apply the changes.

Installation

npm install @clickhouse/mcp

Configuration for local development

Create a .env file in your project root with the following environment variables:

Required Variables

• CLICKHOUSE_HOST: The hostname of your ClickHouse server
• CLICKHOUSE_USER: The username for authentication
• CLICKHOUSE_PASSWORD: The password for authentication

Optional Variables

• CLICKHOUSE_PORT: The port number of your ClickHouse server
  • Default: 8443 if HTTPS is enabled, 8123 if disabled
  • Usually doesn't need to be set unless using a non-standard port
• CLICKHOUSE_SECURE: Enable/disable HTTPS connection
  • Default: true
  • Set to false for non-secure connections
• CLICKHOUSE_VERIFY: Enable/disable SSL certificate verification
  • Default: true
  • Set to false to disable certificate verification (not recommended for production)
• CLICKHOUSE_CONNECT_TIMEOUT: Connection timeout in seconds
  • Default: 30
  • Increase this value if you experience connection timeouts
• CLICKHOUSE_SEND_RECEIVE_TIMEOUT: Send/receive timeout in seconds
  • Default: 300
  • Increase this value for long-running queries
• CLICKHOUSE_DATABASE: Default database to use
  • Default: None (uses server default)
  • Set this to automatically connect to a specific database

Development

Setup

1. Clone the repository:

git clone https://github.com/aminkhorramii/mcp-clickhouse-ts.git
cd mcp-clickhouse-ts

2. Install dependencies:

npm install

3. Create a .env file in the root directory with your ClickHouse connection details:

CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_SECURE=false

Running Locally

For development:

npm run dev

Build the project:

npm run build

Run the built version:

npm start

Docker

Build the Docker image:

npm run docker:build

Run with Docker:

docker run -e CLICKHOUSE_HOST=your-host -e CLICKHOUSE_USER=your-user -e CLICKHOUSE_PASSWORD=your-password mcp-clickhouse-ts

Example Usage

Once the MCP server is connected to Claude, you can interact with ClickHouse using natural language:

• "List all databases in my ClickHouse instance"
• "Run this SQL query: SELECT count() FROM system.tables"
• "Show me the schema of the 'users' table in the 'default' database"

Example Configurations

For local development with Docker:

# Required variables
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

# Optional: Override defaults for local development
CLICKHOUSE_SECURE=false  # Uses port 8123 automatically
CLICKHOUSE_VERIFY=false

For ClickHouse Cloud:

# Required variables
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password

# Optional: These use secure defaults
# CLICKHOUSE_SECURE=true  # Uses port 8443 automatically
# CLICKHOUSE_DATABASE=your_database

License

MIT