clickhouse_mcp_server

This MCP server exposes ClickHouse databases and tables as resources that can be discovered, inspected, and queried by clients using the MCP protocol. It can list available ClickHouse databases and tables, retrieve table schemas, and execute SELECT queries against the ClickHouse instance. To use it, start the server with Python and ensure the ClickHouse connection details are provided via environment variables or by editing the get_clickhouse_client function in server.py. Once running, clients can query for resources like databases, tables, and schemas, and send SELECT statements to retrieve data from ClickHouse through the MCP interface. The server handles the MCP messaging, resource discovery, and safe query execution, enabling seamless integration with LLMs and other AI tools.

Prerequisites:

• Python 3.10+
• Access to a running ClickHouse server
• Git

Installation steps:

1. Clone the repository: git clone https://github.com/ThomAub/clickhouse_mcp_server.git cd clickhouse_mcp_server

2. Install dependencies (via uv, as per project instructions): uv sync --all-extras

3. Configure ClickHouse connection:

   • Set environment variables as described in the mcp_config (or edit server.py to customize the connection).
   • Example (bash): export CLICKHOUSE_HOST=localhost export CLICKHOUSE_PORT=9000 export CLICKHOUSE_USER=default export CLICKHOUSE_PASSWORD= export CLICKHOUSE_DATABASE=default

4. Run the server: python clickhouse_mcp_server/server.py

5. (Optional) Run tests: pytest tests/

Tips and notes:

• Ensure the ClickHouse server is reachable from the MCP server host and that the credentials have access to the target databases.
• If you change the ClickHouse connection details, restart the MCP server to apply the new configuration.
• The MCP server supports listing databases and tables, retrieving table schemas, and executing SELECT queries. Use MCP-compatible clients to interact with these capabilities.
• If you encounter authentication or network issues, verify firewall rules and that the ClickHouse user has the necessary privileges.
• You can customize logging via the LOG_LEVEL environment variable for easier debugging (e.g., DEBUG, INFO, WARN).
• For production, consider setting up proper TLS/HTTPS and securing MCP communications as needed by your deployment environment.