MCP ClickHouse Server

Common errors

• ModuleNotFoundError: No module named 'mcp_clickhouse.server'

  cause Attempting to import a subpackage directly (e.g., `import mcp_clickhouse.server`) that is not explicitly exposed as a top-level module, or is missing an `__init__.py` to mark it as a package.
  fix Import specific modules from the subpackage, e.g., `from mcp_clickhouse.server.main import app` or `from mcp_clickhouse.server.settings import ServerSettings`.

• RuntimeError: Failed to connect to ClickHouse at clickhouse://user:****@localhost:8123/default, reason: ...

  cause The `mcp-clickhouse` server could not establish a connection to the specified ClickHouse database. This typically indicates an incorrect database URL, inaccessible host/port, or invalid credentials.
  fix Verify that your ClickHouse server is running and accessible from the `mcp-clickhouse` host. Double-check the `MCP_CLICKHOUSE_DB_URL` environment variable for correct host, port, username, password, and database name.

• uvicorn.workers.UvicornWorker - Application startup failed. Exiting.

  cause A general error occurred during the FastAPI application's startup phase, often due to missing or invalid required configuration (environment variables) or other internal exceptions preventing the server from initializing.
  fix Examine the full traceback in the server logs for more specific error messages. Ensure all critical environment variables (like `MCP_CLICKHOUSE_DB_URL`) are correctly set and accessible to the `mcp-clickhouse` process.

Warnings

• breaking As a pre-1.0.0 library, internal APIs and configuration options may change between minor versions (e.g., 0.x.y to 0.x+1.z) without explicit breaking change notices. Always refer to the latest source for API stability.
  Fix: Consult the `pyproject.toml` for up-to-date dependencies and `mcp_clickhouse/server/settings.py` for current environment variable configuration keys when upgrading minor versions.
• gotcha The MCP ClickHouse server requires an external ClickHouse database instance to connect to. It does not embed or manage a ClickHouse server itself.
  Fix: Ensure a running ClickHouse instance is accessible from where `mcp-clickhouse` is deployed, and that its connection details are correctly configured via the `MCP_CLICKHOUSE_DB_URL` environment variable.
• gotcha Configuration for the server, including database connection details and other settings, is primarily managed through environment variables (e.g., `MCP_CLICKHOUSE_DB_URL`), following Pydantic Settings conventions. There is no traditional configuration file.
  Fix: Set all required `MCP_CLICKHOUSE_` prefixed environment variables in your deployment environment or provide them via a `.env` file loaded at application startup.

Install

• pip install mcp-clickhouse Install stable version

Imports

• app

  from mcp_clickhouse.server.main import app

Quickstart

This quickstart demonstrates how to programmatically run the MCP ClickHouse server using uvicorn. Note that `MCP_CLICKHOUSE_DB_URL` must be set for the server to function correctly. After running, you can access the API at `http://localhost:8000` (e.g., `http://localhost:8000/health`). For typical use, the CLI command `mcp-clickhouse start` is also available after installation.

import uvicorn
import os
from mcp_clickhouse.server.main import app

# Set required environment variables for ClickHouse connection
# In a real scenario, you would provide actual credentials or use a .env file.
os.environ['MCP_CLICKHOUSE_DB_URL'] = os.environ.get('MCP_CLICKHOUSE_DB_URL', 'clickhouse://user:password@localhost:8123/default')

if __name__ == "__main__":
    print(f"Starting MCP ClickHouse server on http://0.0.0.0:8000")
    print(f"Using ClickHouse DB URL: {os.environ['MCP_CLICKHOUSE_DB_URL']}")
    uvicorn.run(app, host="0.0.0.0", port=8000)