You can run a single MCP server that both queries ClickHouse databases and manages ClickHouse Cloud infrastructure, or use them separately. This MCP server combination gives you safe, read‑only data exploration by default, with optional write access and full cloud management when you enable it. It’s designed to help you build end‑to‑end data workflows—from data access and analysis to infrastructure control—while enforcing protections that prevent inadvertent data changes or unauthorized cloud actions.

How to use

You interact with the MCP server through an MCP client to perform database queries and cloud management tasks. When you start with database operations only, you can connect to local, self‑hosted, or cloud databases and run read‑only SELECT queries. If you want to manage ClickHouse Cloud infrastructure, you add cloud API credentials and enable the cloud management tools. You can enable both capabilities together for a full workflow from infrastructure to data.

How to install

Prerequisites: you need Python installed (for MCP server tooling) and an environment where you can run the MCP command flow. You will also use the MCP host command to run the server from your CLI. Follow these steps to install and run the MCP server.

# Option 1: Install with uv (recommended for Claude Desktop users)
uv add chmcp

• This installs the MCP server as a ready‑to‑use integration with the CLI orchestrator.

Option 2: Install manually from source (if you prefer a local Python environment):

Clone the package repository

git clone https://github.com/oualib/chmcp.git cd chmcp

Install core dependencies

pip install .

Install with development dependencies (optional)

pip install ".[dev]"

Install with test dependencies (optional)

pip install ".[test]"

Install with documentation dependencies (optional)

pip install ".[docs]"

Install with all optional dependencies (optional)

pip install ".[dev,test,docs]"

Prepare environment (adjust values to your setup)

cp .env.example .env

Edit .env with your configuration

## Configuration overview

You configure access for database operations and cloud management by setting environment variables. The following sections summarize required and optional variables, safety considerations, and example safe/production configurations.

## Database configuration

Required environment variables to enable database operations:

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

Safety and security variables to enforce read‑only access by default:

CLICKHOUSE_READONLY=true # Enable read-only mode (recommended)

true: Only SELECT/SHOW/DESCRIBE queries allowed

false: All SQL operations permitted

Optional variables with defaults (adjust as needed):

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

## Cloud API configuration

To enable cloud management, provide API credentials and control the scope of actions with safety settings.

Required variables for cloud access:

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 and access controls for cloud operations:

CLICKHOUSE_CLOUD_READONLY=false # Cloud operation mode (default: false)

true: Only read operations (list, get, metrics)

false: All cloud operations permitted (create, update, delete)

## Getting API keys and configuring permissions

To obtain API keys: log into ClickHouse Cloud Console, go to Settings > API Keys, create an API key, and copy the Key ID and Key Secret to your environment or secret store.

## Security and safety notes

Always run in the minimal‑privilege mode for production. Use SSL by default and avoid embedding credentials in code. Use dedicated database users with limited permissions for MCP connections. Implement timeouts to prevent runaway queries and operations.

## Usage examples

Database operations example pattern focuses on read‑only queries for data analysis and schema exploration. Cloud management examples demonstrate monitoring as read‑only and full management actions when explicitly allowed by configuration.

## Troubleshooting

If you run into connection or SSL issues, verify host, user, and password, check network access, and consider temporarily disabling SSL verification to isolate problems. For cloud issues, confirm API key permissions and ensure the correct readonly mode is active for your use case.

## Available tools

### list\_databases

Return the list of available databases on the connected ClickHouse server.

### list\_tables

Return tables and metadata for a given database, including schema and row counts.

### run\_query

Execute SQL queries with safety controls based on read-only mode. In read-only mode, only safe operations are allowed.

### cloud\_list\_organizations

List organizations in ClickHouse Cloud when cloud access is enabled.

### cloud\_get\_organization

Get details of a specific organization.

### cloud\_list\_services

List services within an organization.

### cloud\_get\_service

Get details for a specific cloud service.

### cloud\_get\_service\_metrics

Retrieve performance metrics for a cloud service.

### cloud\_list\_api\_keys

List API keys for an organization.

### cloud\_get\_api\_key

Get details of an API key.

### cloud\_list\_members

List members of an organization.

### cloud\_get\_member

Get details of a organization member.

### cloud\_list\_backups

List service backups for an organization.

### cloud\_get\_backup

Get backup details for a service.

### cloud\_list\_activities

Get audit logs for an organization.

### cloud\_get\_activity

Get details of a specific activity.

### cloud\_get\_usage\_cost

Retrieve usage cost analytics for an organization.

### cloud\_update\_organization

Update organization settings.

### cloud\_create\_service

Create a new cloud service with specified configuration.

### cloud\_update\_service

Update settings for an existing cloud service.

### cloud\_update\_service\_state

Start or stop a cloud service.

### cloud\_update\_backup\_configuration

Configure or update backup settings for a service.

### cloud\_create\_clickpipe

Create a ClickPipe for data ingestion.

### cloud\_update\_clickpipe

Update an existing ClickPipe.

### cloud\_delete\_service

Delete a cloud service.

### cloud\_create\_api\_key

Create a new API key for an organization.

### cloud\_update\_api\_key

Update an API key.

### cloud\_delete\_api\_key

Delete an API key.

### cloud\_update\_member\_role

Update a member's role in an organization.

### cloud\_remove\_member

Remove a member from an organization.

### cloud\_create\_invitation

Send an invitation to join an organization.

### cloud\_delete\_invitation

Cancel a pending invitation.

### cloud\_update\_from\_...

Update backup configuration for a service.

### cloud\_create\_reverse\_private\_endpoint

Create a reverse private endpoint for a service.

### cloud\_get\_reverse\_private\_endpoint

Get details about a reverse private endpoint.

### cloud\_delete\_reverse\_private\_endpoint

Delete a reverse private endpoint.