What is Mcp Clikchouse Ts

mcp-clikchouse-ts is a Model Context Protocol (MCP) server for ClickHouse, developed in TypeScript. It is based on a Python package and allows integration with various applications, such as Claude Desktop.

Use cases

Use cases include integrating ClickHouse with desktop applications for data analysis, building data-driven applications that require fast querying capabilities, and using it in development environments for testing and experimentation.

How to use

To use mcp-clikchouse-ts, you need to configure your application by adding the MCP server settings in the configuration file. You can install it using npm with the command ‘npm install @clickhouse/mcp’ and set environment variables for ClickHouse connection.

Key features

Key features include easy integration with Claude Desktop, support for secure connections, customizable environment variables for connection settings, and compatibility with ClickHouse SQL Playground.

Where to use

mcp-clikchouse-ts can be used in data analytics, business intelligence applications, and any project that requires efficient data querying and management with ClickHouse.

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