chmcp

This MCP server, chmcp, provides two core capabilities: Database Operations for interacting with ClickHouse databases and Cloud Management for controlling ClickHouse Cloud infrastructure via API. You can use one or both capabilities in a single MCP server deployment. The database tools enable safe, read-only querying, schema exploration, and metadata discovery across local, self-hosted, or cloud-hosted ClickHouse instances. The cloud tools give programmatic control over ClickHouse Cloud resources, including organizations, services, API keys, members, backups, and data pipelines. When configuring access, you typically supply database credentials (host, port, user, password) and, if using Cloud features, API keys and org/service identifiers. The server enforces safety modes by default (read-only queries, restricted operations) with options to override as needed for administrative tasks.

Prerequisites:

• Python 3.12 or newer installed on your system
• Internet access to install Python packages
• Access credentials for ClickHouse (host, port, user, password) and optional ClickHouse Cloud API keys if you plan to use Cloud features

Install steps:

1. Create a Python virtual environment (optional but recommended):

python -m venv venv
source venv/bin/activate  # on Unix/macOS
venv\Scripts\activate     # on Windows

2. Install the MCP server package from PyPI:

pip install chmcp

3. Run the MCP server module (example used in this documentation):

python -m chmcp

4. If you require environment-based configuration, set up environment variables as described in the mcp_config section and run the server from your deployment tooling (e.g., uv, systemd, or a container).

Optional: If you prefer containerized deployment, you can build/run with Docker using the image that provides the chmcp server and pass the required environment variables.

Tips and common considerations:

• By default, the database operations run in read-only mode to prevent unintended data modifications. Adjust via environment variable CLICKHOUSE_READONLY or specific tool configuration if you need write access (use with caution).
• For Cloud operations, ensure your API keys and organization/service IDs are kept secure. Do not hardcode credentials in code or configuration files that are checked into version control.
• If you encounter connectivity issues to ClickHouse, verify TLS/SSL settings (CLICKHOUSE_SECURE) and correct host/port values. Ensure network access and firewall rules permit the required connections.
• The MCP server supports both single-use and multi-use configurations. You can enable or disable specific capabilities by adjusting the environment and command arguments per your deployment.
• Review the official documentation/tutorials referenced in the README for advanced usage, such as complete setup workflows and the full set of Cloud management tools.