Chmcp

MCP ClickHouse: Database Operations + Cloud Management

[](https://pypi.org/project/chmcp)

[](https://opensource.org/licenses/Apache-2.0) [](https://github.com/psf/black) [](https://github.com/astral-sh/ruff)

A comprehensive Model Context Protocol (MCP) server that provides two distinct capabilities:

1. Database Operations - Connect to and query any ClickHouse database (local, cloud, or self-hosted)
2. Cloud Management - Complete ClickHouse Cloud infrastructure management via API

🚀 Quick Start

Start with our step-by-step tutorial:

👉 Complete Setup Tutorial - Transform Claude into a powerful ClickHouse data agent

For experienced users, jump to the [Quick Configuration](#quick-configuration) section below.

📚 Table of Contents

• [🚀 Quick Start](#-quick-start)
• [📚 Table of Contents](#-table-of-contents)
• [🎯 Choose Your Use Case](#-choose-your-use-case)
• [🌟 Why This Server?](#-why-this-server)
• [✨ Capabilities Overview](#-capabilities-overview)
• [🔒 Safety Features](#-safety-features)
• [⚡ Quick Configuration](#-quick-configuration)
• [📦 Installation](#-installation)
• [⚙️ Configuration Guide](#️-configuration-guide)
• [🛠️ Available Tools](#️-available-tools)
• [💡 Usage Examples](#-usage-examples)
• [🔧 Development](#-development)
• [🐛 Troubleshooting](#-troubleshooting)
• [📄 License](#-license)

🎯 Choose Your Use Case

This MCP server supports two independent use cases. You can use one or both:

📊 Database Operations Only

For: Data analysis, querying, and exploration of ClickHouse databases

• Connect to any ClickHouse instance (local, self-hosted, or ClickHouse Cloud)
• Execute read-only queries safely
• Explore database schemas and metadata
• Setup: Database connection credentials only

☁️ Cloud Management Only

For: Managing ClickHouse Cloud infrastructure programmatically

• Create, configure, and manage cloud services
• Handle API keys, members, and organizations
• Monitor usage, costs, and performance
• Setup: ClickHouse Cloud API keys only

🔄 Both Combined

For: Complete ClickHouse workflow from infrastructure to data

• Manage cloud services AND query the databases within them
• End-to-end data pipeline management
• Setup: Both database credentials and cloud API keys

🌟 Why This Server?

This repository significantly improves over the original ClickHouse MCP server:

| Feature | Original Server (v0.1.10) | This Server | |---------|----------------|-------------| | Database Operations | 3 basic tools | 3 enhanced tools with safety features | | Query Security | ❌ run_select_query allows ANY SQL operation | ✅ Proper query filtering and readonly mode | | Cloud Management | ❌ None | ✅ 50+ comprehensive tools (100% API coverage) | | Safety Controls | ❌ No protection against destructive operations | ✅ Advanced readonly modes for both database and cloud operations | | Code Quality | Basic | Production-ready with proper structure | | Configuration | Limited options | Flexible setup for any use case | | Error Handling | Basic | Robust with detailed error messages | | SSL Support | Limited | Full SSL configuration options |

> [!WARNING] > Security Notice: The original ClickHouse MCP server (v0.1.10) has a critical security flaw where run_select_query can execute ANY SQL operation including DROP, DELETE, INSERT, etc., despite its name suggesting it only runs SELECT queries. This server implements proper query filtering and safety controls.

✨ Capabilities Overview

📊 Database Operations (3 Tools)

Connect to and query any ClickHouse database:

• List databases and tables with detailed metadata
• Execute SELECT queries with safety guarantees (read-only mode)
• Explore schemas including column types, row counts, and table structures
• Works with: Local ClickHouse, self-hosted instances, ClickHouse Cloud databases, and the free SQL Playground

☁️ Cloud Management (50+ Tools)

Complete ClickHouse Cloud API integration:

• Organizations (5 tools): Manage settings, metrics, private endpoints
• Services (12 tools): Create, scale, start/stop, configure, delete cloud services
• API Keys (5 tools): Full CRUD operations for programmatic access
• Members & Invitations (8 tools): User management and access control
• Backups (4 tools): Configure and manage automated backups
• ClickPipes (7 tools): Data ingestion pipeline management
• Monitoring (3 tools): Usage analytics, costs, and audit logs
• Network (6 tools): Private endpoints and security configuration

🔒 Safety Features

This MCP server includes comprehensive safety controls to prevent accidental data modification or infrastructure changes:

📊 Database Safety

• Automatic Read-Only Mode: All database queries run with readonly = 1 by default
• Query Filtering: Only SELECT, SHOW, DESCRIBE, and EXPLAIN queries are allowed
• Manual Override: Set CLICKHOUSE_READONLY=false to enable write operations when needed

☁️ Cloud Management Safety

• Protected Operations: Destructive cloud operations (delete, stop) can be enabled
• Safe Mode: Set CLICKHOUSE_CLOUD_READONLY=false to allow infrastructure changes
• Audit Trail: All operations are logged for accountability

🛡️ Security Best Practices

• Minimal Privileges: Create dedicated users with limited permissions
• SSL by Default: Secure connections enabled automatically
• Environment Variables: Sensitive credentials never hardcoded
• Timeout Controls: Prevent runaway queries and operations

⚡ Quick Configuration

Claude Desktop Setup

1. Open your Claude Desktop configuration file:

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

1. Choose your configuration based on your use case:

📊 Database Operations Only (Click to expand)

For Your Own ClickHouse Server

{
  "mcpServers": {
    "chmcp": {
      "command": "/path/to/uv",
      "args": ["run", "--with", "chmcp", "--python", "3.13", "chmcp"],
      "env": {
        "CLICKHOUSE_HOST": "your-server.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "your-username",
        "CLICKHOUSE_PASSWORD": "your-password",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_READONLY": "true"
      }
    }
  }
}

For ClickHouse Cloud Database

{
  "mcpServers": {
    "chmcp": {
      "command": "/path/to/uv",
      "args": ["run", "--with", "chmcp", "--python", "3.13", "chmcp"],
      "env": {
        "CLICKHOUSE_HOST": "your-instance.clickhouse.cloud",
        "CLICKHOUSE_USER": "default",
        "CLICKHOUSE_PASSWORD": "your-database-password",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_READONLY": "true"
      }
    }
  }
}

For Free Testing (SQL Playground)

{
  "mcpServers": {
    "chmcp": {
      "command": "/path/to/uv",
      "args": ["run", "--with", "chmcp", "--python", "3.13", "chmcp"],
      "env": {
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_READONLY": "true"
      }
    }
  }
}

☁️ Cloud Management Only (Click to expand)

{
  "mcpServers": {
    "chmcp": {
      "command": "/path/to/uv",
      "args": ["run", "--with", "chmcp", "--python", "3.13", "chmcp"],
      "env": {
        "CLICKHOUSE_CLOUD_KEY_ID": "your-cloud-key-id",
        "CLICKHOUSE_CLOUD_KEY_SECRET": "your-cloud-key-secret"
      }
    }
  }
}

> Note: CLICKHOUSE_CLOUD_READONLY defaults to true (monitoring-only mode). Add "CLICKHOUSE_CLOUD_READONLY": "false" for full access.

🔄 Both Database + Cloud Management (Click to expand)

{
  "mcpServers": {
    "chmcp": {
      "command": "/path/to/uv",
      "args": ["run", "--with", "chmcp", "--python", "3.13", "chmcp"],
      "env": {
        "CLICKHOUSE_HOST": "your-instance.clickhouse.cloud",
        "CLICKHOUSE_USER": "default",
        "CLICKHOUSE_PASSWORD": "your-database-password",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_READONLY": "true",
        "CLICKHOUSE_CLOUD_KEY_ID": "your-cloud-key-id",
        "CLICKHOUSE_CLOUD_KEY_SECRET": "your-cloud-key-secret"
      }
    }
  }
}

> Note: This enables database analysis (readonly) + full cloud management. Add "CLICKHOUSE_CLOUD_READONLY": "true" for monitoring-only mode.

1. Important: Replace /path/to/uv with the absolute path to your uv executable (find it with which uv on macOS/Linux)

1. Restart Claude Desktop to apply the changes

📦 Installation

Option 1: Using uv (Recommended)

# Install via uv (used by Claude Desktop)
uv add chmcp

Option 2: Manual Installation

# Clone the repository
git clone https://github.com/oualib/chmcp.git
cd chmcp

# Install core dependencies
pip install .

# Install with development dependencies
pip install ".[dev]"

# Install with test dependencies
pip install ".[test]"

# Install with documentation dependencies
pip install ".[docs]"

# Install with all optional dependencies
pip install ".[dev,test,docs]"

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

⚙️ Configuration Guide

📊 Database Configuration

Set these environment variables to enable database operations:

Required Variables

CLICKHOUSE_HOST=your-clickhouse-host.com   # ClickHouse server hostname
CLICKHOUSE_USER=your-username              # Username for authentication
CLICKHOUSE_PASSWORD=your-password          # Password for authentication

Safety & Security Variables

CLICKHOUSE_READONLY=true                   # Enable read-only mode (recommended)
                                           # true: Only SELECT/SHOW/DESCRIBE queries allowed
                                           # false: All SQL operations permitted

Optional Variables (with defaults)

CLICKHOUSE_PORT=8443                        # 8443 for HTTPS, 8123 for HTTP
CLICKHOUSE_SECURE=true                      # Enable HTTPS connection
CLICKHOUSE_VERIFY=true                      # Verify SSL certificates
CLICKHOUSE_CONNECT_TIMEOUT=30               # Connection timeout in seconds
CLICKHOUSE_SEND_RECEIVE_TIMEOUT=300         # Query timeout in seconds
CLICKHOUSE_DATABASE=default                 # Default database to use

> [!CAUTION] > Security Best Practice: Always use CLICKHOUSE_READONLY=true in production environments. Create a dedicated database user with minimal privileges for MCP connections. Avoid using administrative accounts.

☁️ Cloud API Configuration

Set these environment variables to enable cloud management:

Required Variables

CLICKHOUSE_CLOUD_KEY_ID=your-cloud-key-id          # From ClickHouse Cloud Console
CLICKHOUSE_CLOUD_KEY_SECRET=your-cloud-key-secret  # From ClickHouse Cloud Console

Safety & Security Variables

CLICKHOUSE_CLOUD_READONLY=false            # Cloud operation mode (default: false)
                                           # true: Only read operations (list, get, metrics)
                                           # false: All cloud operations permitted (create, update, delete)

Optional Variables (with defaults)

CLICKHOUSE_CLOUD_API_URL=https://api.clickhouse.cloud   # API endpoint
CLICKHOUSE_CLOUD_TIMEOUT=30                             # Request timeout
CLICKHOUSE_CLOUD_SSL_VERIFY=true                        # SSL verification

> [!WARNING] > Cloud Safety: By default, CLICKHOUSE_CLOUD_READONLY=false allows all infrastructure operations. Set to true in production to prevent accidental infrastructure changes. When disabled, Claude can create, modify, and delete cloud services, which may incur costs or cause service disruptions.

🔑 Getting ClickHouse Cloud API Keys

1. Log into ClickHouse Cloud Console
2. Navigate to Settings → API Keys
3. Click Create API Key
4. Select appropriate permissions:

• Admin: Full access to all resources
• Developer: Service and resource management
• Query Endpoints: Limited to query operations

1. Copy the Key ID and Key Secret to your configuration

🔒 Safety Configuration Examples

Production Safe Mode (Recommended)

# Database - read-only queries only
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=readonly_user
CLICKHOUSE_PASSWORD=secure-password
CLICKHOUSE_SECURE=true
CLICKHOUSE_READONLY=true

# Cloud - monitoring and inspection only (explicitly set to true)
CLICKHOUSE_CLOUD_KEY_ID=your-cloud-key-id
CLICKHOUSE_CLOUD_KEY_SECRET=your-cloud-key-secret
CLICKHOUSE_CLOUD_READONLY=true

Development Mode (Full Access)

# Database - all operations allowed
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_SECURE=false
CLICKHOUSE_READONLY=false

# Cloud - full infrastructure management
CLICKHOUSE_CLOUD_KEY_ID=dev-key-id
CLICKHOUSE_CLOUD_KEY_SECRET=dev-key-secret
CLICKHOUSE_CLOUD_READONLY=false

Analysis Only Mode

# Database - read-only for data analysis
CLICKHOUSE_HOST=analytics.company.com
CLICKHOUSE_USER=analyst
CLICKHOUSE_PASSWORD=analyst-password
CLICKHOUSE_SECURE=true
CLICKHOUSE_READONLY=true

# Cloud - monitoring only, no infrastructure changes
CLICKHOUSE_CLOUD_KEY_ID=monitoring-key-id
CLICKHOUSE_CLOUD_KEY_SECRET=monitoring-key-secret
CLICKHOUSE_CLOUD_READONLY=true

Example Configurations

Local Development with Docker

# Database only - full access for development
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_SECURE=false
CLICKHOUSE_PORT=8123
CLICKHOUSE_READONLY=false

ClickHouse Cloud (Safe Mode)

# Database connection - read-only
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-database-password
CLICKHOUSE_SECURE=true
CLICKHOUSE_READONLY=true

# Cloud management - monitoring only (explicitly set to true)
CLICKHOUSE_CLOUD_KEY_ID=your-cloud-key-id
CLICKHOUSE_CLOUD_KEY_SECRET=your-cloud-key-secret
CLICKHOUSE_CLOUD_READONLY=true

SSL Issues Troubleshooting

If you encounter SSL certificate verification issues:

# Disable SSL verification for database
CLICKHOUSE_VERIFY=false
CLICKHOUSE_SECURE=false  # Use HTTP instead of HTTPS
CLICKHOUSE_PORT=8123     # HTTP port instead of 8443

# Disable SSL verification for cloud API
CLICKHOUSE_CLOUD_SSL_VERIFY=false

🛠️ Available Tools

📊 Database Tools (3 tools)

These tools work with any ClickHouse database when database configuration is provided:

• list_databases() - List all available databases
• list_tables(database, like?, not_like?) - List tables with detailed metadata including schema, row counts, and column information
• run_query(query) - Execute queries with safety controls:
• Read-only mode (CLICKHOUSE_READONLY=true): Only SELECT, SHOW, DESCRIBE, EXPLAIN queries
• Full access mode (CLICKHOUSE_READONLY=false): All SQL operations including INSERT, UPDATE, DELETE, CREATE, DROP

> [!NOTE] > Query Safety: When CLICKHOUSE_READONLY=true, all queries automatically run with readonly = 1 setting and are filtered to prevent data modification operations.

☁️ Cloud Management Tools (50+ tools)

These tools work with ClickHouse Cloud when API credentials are provided. Tool availability depends on the CLICKHOUSE_CLOUD_READONLY setting:

🔍 Read-Only Operations (Available when CLICKHOUSE_CLOUD_READONLY=true)

Organization Monitoring (3 tools)

• cloud_list_organizations() - List available organizations
• `cloud

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: oualib
• Source: oualib/chmcp
• License: Apache-2.0
• Homepage: https://clickhouse.com/

Install and usage instructions live in the source repository linked above.