{"id":9923,"library":"mcp-clickhouse","title":"MCP ClickHouse Server","description":"An MCP server for ClickHouse. This library provides a FastAPI-based application that allows configuration of a ClickHouse database via MCP (Mediation Control Plane) and fetches data using a REST API. It is currently at version 0.3.0 and typically follows an iterative release cadence with feature additions and bug fixes.","status":"active","version":"0.3.0","language":"en","source_language":"en","source_url":"https://github.com/Mediation-Control-Plane/mcp-clickhouse","tags":["clickhouse","fastapi","server","api","mqtt","database"],"install":[{"cmd":"pip install mcp-clickhouse","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core web framework for the API server.","package":"fastapi"},{"reason":"ASGI server to run the FastAPI application.","package":"uvicorn"},{"reason":"For MQTT client integration.","package":"asyncio_mqtt"},{"reason":"Client library for interacting with ClickHouse database.","package":"clickhouse-connect"},{"reason":"For data validation and managing server settings from environment variables.","package":"pydantic"},{"reason":"For loading environment variables from .env files.","package":"python-dotenv"},{"reason":"For structured JSON logging.","package":"python-json-logger"},{"reason":"For JSON Web Token (JWT) handling and authentication.","package":"python-jose"},{"reason":"For building the command-line interface (CLI) to run the server.","package":"typer"}],"imports":[{"symbol":"app","correct":"from mcp_clickhouse.server.main import app"}],"quickstart":{"code":"import uvicorn\nimport os\nfrom mcp_clickhouse.server.main import app\n\n# Set required environment variables for ClickHouse connection\n# In a real scenario, you would provide actual credentials or use a .env file.\nos.environ['MCP_CLICKHOUSE_DB_URL'] = os.environ.get('MCP_CLICKHOUSE_DB_URL', 'clickhouse://user:password@localhost:8123/default')\n\nif __name__ == \"__main__\":\n    print(f\"Starting MCP ClickHouse server on http://0.0.0.0:8000\")\n    print(f\"Using ClickHouse DB URL: {os.environ['MCP_CLICKHOUSE_DB_URL']}\")\n    uvicorn.run(app, host=\"0.0.0.0\", port=8000)","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions < 1.0.0"},{"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.","message":"The MCP ClickHouse server requires an external ClickHouse database instance to connect to. It does not embed or manage a ClickHouse server itself.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set all required `MCP_CLICKHOUSE_` prefixed environment variables in your deployment environment or provide them via a `.env` file loaded at application startup.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Import specific modules from the subpackage, e.g., `from mcp_clickhouse.server.main import app` or `from mcp_clickhouse.server.settings import ServerSettings`.","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.","error":"ModuleNotFoundError: No module named 'mcp_clickhouse.server'"},{"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.","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.","error":"RuntimeError: Failed to connect to ClickHouse at clickhouse://user:****@localhost:8123/default, reason: ..."},{"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.","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.","error":"uvicorn.workers.UvicornWorker - Application startup failed. Exiting."}]}