[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"tool-ClickHouse--mcp-clickhouse":3,"similar-ClickHouse--mcp-clickhouse":93},{"id":4,"github_repo":5,"name":6,"description_en":7,"description_zh":8,"ai_summary_zh":8,"readme_en":9,"readme_zh":10,"quickstart_zh":11,"use_case_zh":12,"hero_image_url":13,"owner_login":14,"owner_name":14,"owner_avatar_url":15,"owner_bio":16,"owner_company":17,"owner_location":17,"owner_email":18,"owner_twitter":19,"owner_website":20,"owner_url":21,"languages":22,"stars":31,"forks":32,"last_commit_at":33,"license":34,"difficulty_score":35,"env_os":36,"env_gpu":37,"env_ram":37,"env_deps":38,"category_tags":45,"github_topics":17,"view_count":35,"oss_zip_url":17,"oss_zip_packed_at":17,"status":48,"created_at":49,"updated_at":50,"faqs":51,"releases":82},5876,"ClickHouse\u002Fmcp-clickhouse","mcp-clickhouse","Connect ClickHouse to your AI assistants.","mcp-clickhouse 是一款专为 AI 助手设计的桥梁工具，旨在让大语言模型能够直接连接并操作 ClickHouse 数据库。它解决了传统模式下 AI 无法实时访问企业级数据仓库、需依赖繁琐中间件或手动导出数据的痛点，使开发者能通过自然语言指令让 AI 自动执行 SQL 查询、浏览数据库结构或直接分析本地文件。\n\n该工具主要面向后端开发者、数据工程师及构建 AI 应用的研究人员。通过集成 Model Context Protocol (MCP) 标准，mcp-clickhouse 提供了丰富的功能集：既支持对远程 ClickHouse 集群进行安全的只读查询、分页列出库表结构，也内置了 chDB 引擎，允许无需 ETL 过程即可直接查询本地文件或 URL 中的数据。此外，它还具备完善的健康检查机制和灵活的认证配置，确保在生产环境 HTTP\u002FSSE 传输模式下的安全性，同时保留本地开发模式的便捷性。无论是需要快速验证数据原型的工程师，还是希望为 AI 代理赋予实时数据洞察能力的团队，mcp-clickhouse 都能提供高效、安全且低门槛的解决方案。","# ClickHouse MCP Server\n\n[![PyPI - Version](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fmcp-clickhouse)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fmcp-clickhouse)\n\nAn MCP server for ClickHouse.\n\n\u003Ca href=\"https:\u002F\u002Fglama.ai\u002Fmcp\u002Fservers\u002Fyvjy4csvo1\">\u003Cimg width=\"380\" height=\"200\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FClickHouse_mcp-clickhouse_readme_55e6c7046886.png\" alt=\"mcp-clickhouse MCP server\" \u002F>\u003C\u002Fa>\n\n## Features\n\n### ClickHouse Tools\n\n* `run_query`\n  * Execute SQL queries on your ClickHouse cluster.\n  * Input: `query` (string): The SQL query to execute.\n  * Queries run in read-only mode by default (`CLICKHOUSE_ALLOW_WRITE_ACCESS=false`), but writes can be enabled explicitly if needed.\n\n* `list_databases`\n  * List all databases on your ClickHouse cluster.\n\n* `list_tables`\n  * List tables in a database with pagination.\n  * Required input: `database` (string).\n  * Optional inputs:\n    * `like` \u002F `not_like` (string): Apply `LIKE` or `NOT LIKE` filters to table names.\n    * `page_token` (string): Token returned by a previous call for fetching the next page.\n    * `page_size` (int, default `50`): Number of tables returned per page.\n    * `include_detailed_columns` (bool, default `true`): When `false`, omits column metadata for lighter responses while keeping the full `create_table_query`.\n  * Response shape:\n    * `tables`: Array of table objects for the current page.\n    * `next_page_token`: Pass this value back to fetch the next page, or `null` when there are no more tables.\n    * `total_tables`: Total count of tables that match the supplied filters.\n\n### chDB Tools\n\n* `run_chdb_select_query`\n  * Execute SQL queries using [chDB](https:\u002F\u002Fgithub.com\u002Fchdb-io\u002Fchdb)'s embedded ClickHouse engine.\n  * Input: `query` (string): The SQL query to execute.\n  * Query data directly from various sources (files, URLs, databases) without ETL processes.\n\n### Health Check Endpoint\n\nWhen running with HTTP or SSE transport, a health check endpoint is available at `\u002Fhealth`. This endpoint:\n- Returns `200 OK` with the ClickHouse version if the server is healthy and can connect to ClickHouse\n- Returns `503 Service Unavailable` if the server cannot connect to ClickHouse\n\nExample:\n```bash\ncurl http:\u002F\u002Flocalhost:8000\u002Fhealth\n# Response: OK - Connected to ClickHouse 24.3.1\n```\n\n## Security\n\n### Authentication for HTTP\u002FSSE Transports\n\nWhen using HTTP or SSE transport, authentication is **required by default**. The `stdio` transport (default) does not require authentication as it only communicates via standard input\u002Foutput.\n\n#### Setting Up Authentication\n\n1. Generate a secure token (can be any random string):\n   ```bash\n   # Using uuidgen (macOS\u002FLinux)\n   uuidgen\n\n   # Using openssl\n   openssl rand -hex 32\n   ```\n\n2. Configure the server with the token:\n   ```bash\n   export CLICKHOUSE_MCP_AUTH_TOKEN=\"your-generated-token\"\n   ```\n\n3. Configure your MCP client to include the token in requests:\n\n   For Claude Desktop with HTTP\u002FSSE transport:\n   ```json\n   {\n     \"mcpServers\": {\n       \"mcp-clickhouse\": {\n         \"url\": \"http:\u002F\u002F127.0.0.1:8000\",\n         \"headers\": {\n           \"Authorization\": \"Bearer your-generated-token\"\n         }\n       }\n     }\n   }\n   ```\n\n   For command-line tools:\n   ```bash\n   curl -H \"Authorization: Bearer your-generated-token\" http:\u002F\u002Flocalhost:8000\u002Fhealth\n   ```\n\n#### Development Mode (Disabling Authentication)\n\nFor local development and testing only, you can disable authentication by setting:\n```bash\nexport CLICKHOUSE_MCP_AUTH_DISABLED=true\n```\n\n**WARNING:** Only use this for local development. Do not disable authentication when the server is exposed to any network.\n\n## Configuration\n\nThis MCP server supports both ClickHouse and chDB. You can enable either or both depending on your needs.\n\n1. Open the Claude Desktop configuration file located at:\n   * On macOS: `~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json`\n   * On Windows: `%APPDATA%\u002FClaude\u002Fclaude_desktop_config.json`\n\n2. Add the following:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-clickhouse\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--with\",\n        \"mcp-clickhouse\",\n        \"--python\",\n        \"3.10\",\n        \"mcp-clickhouse\"\n      ],\n      \"env\": {\n        \"CLICKHOUSE_HOST\": \"\u003Cclickhouse-host>\",\n        \"CLICKHOUSE_PORT\": \"\u003Cclickhouse-port>\",\n        \"CLICKHOUSE_USER\": \"\u003Cclickhouse-user>\",\n        \"CLICKHOUSE_PASSWORD\": \"\u003Cclickhouse-password>\",\n        \"CLICKHOUSE_ROLE\": \"\u003Cclickhouse-role>\",\n        \"CLICKHOUSE_SECURE\": \"true\",\n        \"CLICKHOUSE_VERIFY\": \"true\",\n        \"CLICKHOUSE_CONNECT_TIMEOUT\": \"30\",\n        \"CLICKHOUSE_SEND_RECEIVE_TIMEOUT\": \"30\"\n      }\n    }\n  }\n}\n```\n\nUpdate the environment variables to point to your own ClickHouse service.\n\nOr, if you'd like to try it out with the [ClickHouse SQL Playground](https:\u002F\u002Fsql.clickhouse.com\u002F), you can use the following config:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-clickhouse\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--with\",\n        \"mcp-clickhouse\",\n        \"--python\",\n        \"3.10\",\n        \"mcp-clickhouse\"\n      ],\n      \"env\": {\n        \"CLICKHOUSE_HOST\": \"sql-clickhouse.clickhouse.com\",\n        \"CLICKHOUSE_PORT\": \"8443\",\n        \"CLICKHOUSE_USER\": \"demo\",\n        \"CLICKHOUSE_PASSWORD\": \"\",\n        \"CLICKHOUSE_SECURE\": \"true\",\n        \"CLICKHOUSE_VERIFY\": \"true\",\n        \"CLICKHOUSE_CONNECT_TIMEOUT\": \"30\",\n        \"CLICKHOUSE_SEND_RECEIVE_TIMEOUT\": \"30\"\n      }\n    }\n  }\n}\n```\n\nFor chDB (embedded ClickHouse engine), add the following configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-clickhouse\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--with\",\n        \"mcp-clickhouse\",\n        \"--python\",\n        \"3.10\",\n        \"mcp-clickhouse\"\n      ],\n      \"env\": {\n        \"CHDB_ENABLED\": \"true\",\n        \"CLICKHOUSE_ENABLED\": \"false\",\n        \"CHDB_DATA_PATH\": \"\u002Fpath\u002Fto\u002Fchdb\u002Fdata\"\n      }\n    }\n  }\n}\n```\n\nYou can also enable both ClickHouse and chDB simultaneously:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-clickhouse\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--with\",\n        \"mcp-clickhouse\",\n        \"--python\",\n        \"3.10\",\n        \"mcp-clickhouse\"\n      ],\n      \"env\": {\n        \"CLICKHOUSE_HOST\": \"\u003Cclickhouse-host>\",\n        \"CLICKHOUSE_PORT\": \"\u003Cclickhouse-port>\",\n        \"CLICKHOUSE_USER\": \"\u003Cclickhouse-user>\",\n        \"CLICKHOUSE_PASSWORD\": \"\u003Cclickhouse-password>\",\n        \"CLICKHOUSE_SECURE\": \"true\",\n        \"CLICKHOUSE_VERIFY\": \"true\",\n        \"CLICKHOUSE_CONNECT_TIMEOUT\": \"30\",\n        \"CLICKHOUSE_SEND_RECEIVE_TIMEOUT\": \"30\",\n        \"CHDB_ENABLED\": \"true\",\n        \"CHDB_DATA_PATH\": \"\u002Fpath\u002Fto\u002Fchdb\u002Fdata\"\n      }\n    }\n  }\n}\n```\n\n3. Locate the command entry for `uv` and replace it with the absolute path to the `uv` executable. This ensures that the correct version of `uv` is used when starting the server. On a mac, you can find this path using `which uv`.\n\n4. Restart Claude Desktop to apply the changes.\n\n### Optional Write Access\n\nBy default, this MCP enforces read-only queries so that accidental mutations cannot happen during exploration. To allow DDL or INSERT\u002FUPDATE statements, set the `CLICKHOUSE_ALLOW_WRITE_ACCESS` environment variable to `true`. The server keeps enforcing read-only mode if the ClickHouse instance itself disallows writes.\n\n### Destructive Operation Protection\n\nEven when write access is enabled (`CLICKHOUSE_ALLOW_WRITE_ACCESS=true`), destructive operations (DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE) require an additional opt-in flag for safety. This prevents accidental data deletion during AI exploration.\n\nTo enable destructive operations, set both flags:\n```json\n\"env\": {\n  \"CLICKHOUSE_ALLOW_WRITE_ACCESS\": \"true\",\n  \"CLICKHOUSE_ALLOW_DROP\": \"true\"\n}\n```\n\nThis two-tier approach ensures that accidental drops are very difficult:\n- **Write operations** (INSERT, UPDATE, CREATE) require `CLICKHOUSE_ALLOW_WRITE_ACCESS=true`\n- **Destructive operations** (DROP, TRUNCATE) additionally require `CLICKHOUSE_ALLOW_DROP=true`\n\n### Running Without uv (Using System Python)\n\nIf you prefer to use the system Python installation instead of uv, you can install the package from PyPI and run it directly:\n\n1. Install the package using pip:\n   ```bash\n   python3 -m pip install mcp-clickhouse\n   ```\n\n   To upgrade to the latest version:\n   ```bash\n   python3 -m pip install --upgrade mcp-clickhouse\n   ```\n\n2. Update your Claude Desktop configuration to use Python directly:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-clickhouse\": {\n      \"command\": \"python3\",\n      \"args\": [\n        \"-m\",\n        \"mcp_clickhouse.main\"\n      ],\n      \"env\": {\n        \"CLICKHOUSE_HOST\": \"\u003Cclickhouse-host>\",\n        \"CLICKHOUSE_PORT\": \"\u003Cclickhouse-port>\",\n        \"CLICKHOUSE_USER\": \"\u003Cclickhouse-user>\",\n        \"CLICKHOUSE_PASSWORD\": \"\u003Cclickhouse-password>\",\n        \"CLICKHOUSE_SECURE\": \"true\",\n        \"CLICKHOUSE_VERIFY\": \"true\",\n        \"CLICKHOUSE_CONNECT_TIMEOUT\": \"30\",\n        \"CLICKHOUSE_SEND_RECEIVE_TIMEOUT\": \"30\"\n      }\n    }\n  }\n}\n```\n\nAlternatively, you can use the installed script directly:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-clickhouse\": {\n      \"command\": \"mcp-clickhouse\",\n      \"env\": {\n        \"CLICKHOUSE_HOST\": \"\u003Cclickhouse-host>\",\n        \"CLICKHOUSE_PORT\": \"\u003Cclickhouse-port>\",\n        \"CLICKHOUSE_USER\": \"\u003Cclickhouse-user>\",\n        \"CLICKHOUSE_PASSWORD\": \"\u003Cclickhouse-password>\",\n        \"CLICKHOUSE_SECURE\": \"true\",\n        \"CLICKHOUSE_VERIFY\": \"true\",\n        \"CLICKHOUSE_CONNECT_TIMEOUT\": \"30\",\n        \"CLICKHOUSE_SEND_RECEIVE_TIMEOUT\": \"30\"\n      }\n    }\n  }\n}\n```\n\nNote: Make sure to use the full path to the Python executable or the `mcp-clickhouse` script if they are not in your system PATH. You can find the paths using:\n- `which python3` for the Python executable\n- `which mcp-clickhouse` for the installed script\n\n## Custom Middleware\n\nYou can add custom middleware to the MCP server without modifying the source code. FastMCP provides a middleware system that allows you to intercept and process MCP protocol messages (tool calls, resource reads, prompts, etc.).\n\n### How to Use\n\n1. Create a Python module with middleware classes extending `Middleware` and a `setup_middleware(mcp)` function:\n\n```python\n# my_middleware.py\nimport logging\nfrom fastmcp.server.middleware import Middleware, MiddlewareContext, CallNext\n\nlogger = logging.getLogger(\"my-middleware\")\n\nclass LoggingMiddleware(Middleware):\n    \"\"\"Log all tool calls.\"\"\"\n    \n    async def on_call_tool(self, context: MiddlewareContext, call_next: CallNext):\n        tool_name = context.message.name if hasattr(context.message, 'name') else 'unknown'\n        logger.info(f\"Calling tool: {tool_name}\")\n        result = await call_next(context)\n        logger.info(f\"Tool {tool_name} completed\")\n        return result\n\ndef setup_middleware(mcp):\n    \"\"\"Register middleware with the MCP server.\"\"\"\n    mcp.add_middleware(LoggingMiddleware())\n```\n\n2. Set the `MCP_MIDDLEWARE_MODULE` environment variable to the module name (without `.py` extension):\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-clickhouse\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--with\", \"mcp-clickhouse\", \"--python\", \"3.10\", \"mcp-clickhouse\"],\n      \"env\": {\n        \"CLICKHOUSE_HOST\": \"\u003Cclickhouse-host>\",\n        \"CLICKHOUSE_USER\": \"\u003Cclickhouse-user>\",\n        \"CLICKHOUSE_PASSWORD\": \"\u003Cclickhouse-password>\",\n        \"MCP_MIDDLEWARE_MODULE\": \"my_middleware\"\n      }\n    }\n  }\n}\n```\n\n3. Ensure your middleware module is in Python's import path (e.g., in the same directory where the MCP server runs, or installed as a package).\n\n### Example Middleware\n\nAn example middleware module is provided in `example_middleware.py` showing common patterns:\n- Logging all MCP requests\n- Logging tool calls specifically\n- Measuring request processing time\n\nTo use the example:\n```json\n\"env\": {\n  \"MCP_MIDDLEWARE_MODULE\": \"example_middleware\"\n}\n```\n\n### Middleware Capabilities\n\nThe `Middleware` base class provides hooks for different MCP operations:\n\n- `on_message(context, call_next)` - Called for all messages\n- `on_request(context, call_next)` - Called for all requests\n- `on_notification(context, call_next)` - Called for all notifications\n- `on_call_tool(context, call_next)` - Called when a tool is executed\n- `on_read_resource(context, call_next)` - Called when a resource is read\n- `on_get_prompt(context, call_next)` - Called when a prompt is retrieved\n- `on_list_tools(context, call_next)` - Called when listing tools\n- `on_list_resources(context, call_next)` - Called when listing resources\n- `on_list_resource_templates(context, call_next)` - Called when listing resource templates\n- `on_list_prompts(context, call_next)` - Called when listing prompts\n\nEach hook receives a `MiddlewareContext` object containing the message and metadata, and a `call_next` function to continue the pipeline.\n\n### Dynamic Client Configuration via Context State\n\nMiddleware can override ClickHouse client configuration on a per-request basis using the `CLIENT_CONFIG_OVERRIDES_KEY` context state key. The server merges these overrides with the base configuration from environment variables.\n\n```python\nfrom fastmcp.server.dependencies import get_context\nfrom mcp_clickhouse.mcp_server import CLIENT_CONFIG_OVERRIDES_KEY\n\nctx = get_context()\nctx.set_state(CLIENT_CONFIG_OVERRIDES_KEY, {\n    \"connect_timeout\": 60,\n    \"send_receive_timeout\": 120\n})\n```\n\nThis enables advanced use cases like dynamic timeout adjustments, tenant-specific routing, or per-user connection settings.\n\n## Development\n\n1. In `test-services` directory run `docker compose up -d` to start the ClickHouse cluster.\n\n2. Add the following variables to a `.env` file in the root of the repository.\n\n*Note: The use of the `default` user in this context is intended solely for local development purposes.*\n\n```bash\nCLICKHOUSE_HOST=localhost\nCLICKHOUSE_PORT=8123\nCLICKHOUSE_USER=default\nCLICKHOUSE_PASSWORD=clickhouse\n```\n\n3. Run `uv sync` to install the dependencies. To install `uv` follow the instructions [here](https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002F). Then do `source .venv\u002Fbin\u002Factivate`.\n\n4. For easy testing with the MCP Inspector, run `fastmcp dev mcp_clickhouse\u002Fmcp_server.py` to start the MCP server.\n\n5. To test with HTTP transport and the health check endpoint:\n   ```bash\n   # For development, disable authentication\n   CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_DISABLED=true python -m mcp_clickhouse.main\n\n   # Or with authentication (generate a token first)\n   CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_TOKEN=\"your-token\" python -m mcp_clickhouse.main\n\n   # Then in another terminal:\n   # Without auth (if disabled):\n   curl http:\u002F\u002Flocalhost:8000\u002Fhealth\n\n   # With auth:\n   curl -H \"Authorization: Bearer your-token\" http:\u002F\u002Flocalhost:8000\u002Fhealth\n   ```\n\n### Environment Variables\n\nThe following environment variables are used to configure the ClickHouse and chDB connections:\n\n#### ClickHouse Variables\n\n##### Required Variables\n\n* `CLICKHOUSE_HOST`: The hostname of your ClickHouse server\n* `CLICKHOUSE_USER`: The username for authentication\n* `CLICKHOUSE_PASSWORD`: The password for authentication\n\n> [!CAUTION]\n> It is important to treat your MCP database user as you would any external client connecting to your database, granting only the minimum necessary privileges required for its operation. The use of default or administrative users should be strictly avoided at all times.\n\n##### Optional Variables\n\n* `CLICKHOUSE_PORT`: The port number of your ClickHouse server\n  * Default: `8443` if HTTPS is enabled, `8123` if disabled\n  * Usually doesn't need to be set unless using a non-standard port\n* `CLICKHOUSE_ROLE`: The role to use for authentication\n  * Default: None\n  * Set this if your user requires a specific role\n* `CLICKHOUSE_SECURE`: Enable\u002Fdisable HTTPS connection\n  * Default: `\"true\"`\n  * Set to `\"false\"` for non-secure connections\n* `CLICKHOUSE_VERIFY`: Enable\u002Fdisable SSL certificate verification\n  * Default: `\"true\"`\n  * Set to `\"false\"` to disable certificate verification (not recommended for production)\n  * TLS certificates: The package uses your operating system trust store for TLS certificate verification via `truststore`. We call `truststore.inject_into_ssl()` at startup to ensure proper certificate handling. Python’s default SSL behavior is used as a fallback only if an unexpected error occurs.\n* `CLICKHOUSE_CONNECT_TIMEOUT`: Connection timeout in seconds\n  * Default: `\"30\"`\n  * Increase this value if you experience connection timeouts\n* `CLICKHOUSE_SEND_RECEIVE_TIMEOUT`: Send\u002Freceive timeout in seconds\n  * Default: `\"300\"`\n  * Increase this value for long-running queries\n* `CLICKHOUSE_DATABASE`: Default database to use\n  * Default: None (uses server default)\n  * Set this to automatically connect to a specific database\n* `CLICKHOUSE_MCP_SERVER_TRANSPORT`: Sets the transport method for the MCP server.\n  * Default: `\"stdio\"`\n  * Valid options: `\"stdio\"`, `\"http\"`, `\"sse\"`. This is useful for local development with tools like MCP Inspector.\n* `CLICKHOUSE_MCP_BIND_HOST`: Host to bind the MCP server to when using HTTP or SSE transport\n  * Default: `\"127.0.0.1\"`\n  * Set to `\"0.0.0.0\"` to bind to all network interfaces (useful for Docker or remote access)\n  * Only used when transport is `\"http\"` or `\"sse\"`\n* `CLICKHOUSE_MCP_BIND_PORT`: Port to bind the MCP server to when using HTTP or SSE transport\n  * Default: `\"8000\"`\n  * Only used when transport is `\"http\"` or `\"sse\"`\n* `CLICKHOUSE_MCP_QUERY_TIMEOUT`: Timeout in seconds for SELECT tools\n  * Default: `\"30\"`\n  * Increase this if you see `Query timed out after ...` errors for heavy queries\n* `CLICKHOUSE_MCP_AUTH_TOKEN`: Authentication token for HTTP\u002FSSE transports\n  * Default: None\n  * **Required** when using HTTP or SSE transport (unless `CLICKHOUSE_MCP_AUTH_DISABLED=true`)\n  * Generate using `uuidgen` or `openssl rand -hex 32`\n  * Clients must send this token in the `Authorization: Bearer \u003Ctoken>` header\n* `CLICKHOUSE_MCP_AUTH_DISABLED`: Disable authentication for HTTP\u002FSSE transports\n  * Default: `\"false\"` (authentication is enabled)\n  * Set to `\"true\"` to disable authentication for local development\u002Ftesting only\n  * **WARNING:** Only use for local development. Do not disable when exposed to networks\n* `CLICKHOUSE_ENABLED`: Enable\u002Fdisable ClickHouse functionality\n  * Default: `\"true\"`\n  * Set to `\"false\"` to disable ClickHouse tools when using chDB only\n* `CLICKHOUSE_ALLOW_WRITE_ACCESS`: Allow write operations (DDL and DML)\n  * Default: `\"false\"`\n  * Set to `\"true\"` to allow DDL (CREATE, ALTER, DROP) and DML (INSERT, UPDATE, DELETE) operations\n  * When disabled (default), queries run with `readonly=1` setting to prevent data modifications\n* `CLICKHOUSE_ALLOW_DROP`: Allow destructive operations (DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE)\n  * Default: `\"false\"`\n  * Only takes effect when `CLICKHOUSE_ALLOW_WRITE_ACCESS=true` is also set\n  * Set to `\"true\"` to explicitly allow destructive DROP and TRUNCATE operations\n  * This is a safety feature to prevent accidental data deletion during AI exploration\n\n#### Middleware Variables\n\n* `MCP_MIDDLEWARE_MODULE`: Python module name containing custom middleware to inject into the MCP server\n  * Default: None (no middleware loaded)\n  * Set to the module name (without `.py` extension) of your middleware module\n  * The module must provide a `setup_middleware(mcp)` function\n  * See [Custom Middleware](#custom-middleware) for details and examples\n\n#### chDB Variables\n\n* `CHDB_ENABLED`: Enable\u002Fdisable chDB functionality\n  * Default: `\"false\"`\n  * Set to `\"true\"` to enable chDB tools\n* `CHDB_DATA_PATH`: The path to the chDB data directory\n  * Default: `\":memory:\"` (in-memory database)\n  * Use `:memory:` for in-memory database\n  * Use a file path for persistent storage (e.g., `\u002Fpath\u002Fto\u002Fchdb\u002Fdata`)\n\n#### Example Configurations\n\nFor local development with Docker:\n\n```env\n# Required variables\nCLICKHOUSE_HOST=localhost\nCLICKHOUSE_USER=default\nCLICKHOUSE_PASSWORD=clickhouse\n\n# Optional: Override defaults for local development\nCLICKHOUSE_SECURE=false  # Uses port 8123 automatically\nCLICKHOUSE_VERIFY=false\n```\n\nFor ClickHouse Cloud:\n\n```env\n# Required variables\nCLICKHOUSE_HOST=your-instance.clickhouse.cloud\nCLICKHOUSE_USER=default\nCLICKHOUSE_PASSWORD=your-password\n\n# Optional: These use secure defaults\n# CLICKHOUSE_SECURE=true  # Uses port 8443 automatically\n# CLICKHOUSE_DATABASE=your_database\n```\n\nFor ClickHouse SQL Playground:\n\n```env\nCLICKHOUSE_HOST=sql-clickhouse.clickhouse.com\nCLICKHOUSE_USER=demo\nCLICKHOUSE_PASSWORD=\n# Uses secure defaults (HTTPS on port 8443)\n```\n\nFor chDB only (in-memory):\n\n```env\n# chDB configuration\nCHDB_ENABLED=true\nCLICKHOUSE_ENABLED=false\n# CHDB_DATA_PATH defaults to :memory:\n```\n\nFor chDB with persistent storage:\n\n```env\n# chDB configuration\nCHDB_ENABLED=true\nCLICKHOUSE_ENABLED=false\nCHDB_DATA_PATH=\u002Fpath\u002Fto\u002Fchdb\u002Fdata\n```\n\nFor MCP Inspector or remote access with HTTP transport:\n\n```env\nCLICKHOUSE_HOST=localhost\nCLICKHOUSE_USER=default\nCLICKHOUSE_PASSWORD=clickhouse\nCLICKHOUSE_MCP_SERVER_TRANSPORT=http\nCLICKHOUSE_MCP_BIND_HOST=0.0.0.0  # Bind to all interfaces\nCLICKHOUSE_MCP_BIND_PORT=4200  # Custom port (default: 8000)\nCLICKHOUSE_MCP_AUTH_TOKEN=your-generated-token  # Required for HTTP\u002FSSE\n```\n\nFor local development with HTTP transport (authentication disabled):\n\n```env\nCLICKHOUSE_HOST=localhost\nCLICKHOUSE_USER=default\nCLICKHOUSE_PASSWORD=clickhouse\nCLICKHOUSE_MCP_SERVER_TRANSPORT=http\nCLICKHOUSE_MCP_AUTH_DISABLED=true  # Only for local development!\n```\n\nWhen using HTTP transport, the server will run on the configured port (default 8000). For example, with the above configuration:\n- MCP endpoint: `http:\u002F\u002Flocalhost:4200\u002Fmcp`\n- Health check: `http:\u002F\u002Flocalhost:4200\u002Fhealth`\n\nYou can set these variables in your environment, in a `.env` file, or in the Claude Desktop configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-clickhouse\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--with\",\n        \"mcp-clickhouse\",\n        \"--python\",\n        \"3.10\",\n        \"mcp-clickhouse\"\n      ],\n      \"env\": {\n        \"CLICKHOUSE_HOST\": \"\u003Cclickhouse-host>\",\n        \"CLICKHOUSE_USER\": \"\u003Cclickhouse-user>\",\n        \"CLICKHOUSE_PASSWORD\": \"\u003Cclickhouse-password>\",\n        \"CLICKHOUSE_DATABASE\": \"\u003Coptional-database>\",\n        \"CLICKHOUSE_MCP_SERVER_TRANSPORT\": \"stdio\",\n        \"CLICKHOUSE_MCP_BIND_HOST\": \"127.0.0.1\",\n        \"CLICKHOUSE_MCP_BIND_PORT\": \"8000\"\n      }\n    }\n  }\n}\n```\n\nNote: The bind host and port settings are only used when transport is set to \"http\" or \"sse\".\n\n### Running tests\n\n```bash\nuv sync --all-extras --dev # install dev dependencies\nuv run ruff check . # run linting\n\ndocker compose up -d test_services # start ClickHouse\nuv run pytest -v tests\nuv run pytest -v tests\u002Ftest_tool.py # ClickHouse only\nuv run pytest -v tests\u002Ftest_chdb_tool.py # chDB only\n```\n\n## YouTube Overview\n\n[![YouTube](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FClickHouse_mcp-clickhouse_readme_303b784f736f.jpg)](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=y9biAm_Fkqw)\n","# ClickHouse MCP 服务器\n\n[![PyPI - 版本](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fmcp-clickhouse)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fmcp-clickhouse)\n\n一个用于 ClickHouse 的 MCP 服务器。\n\n\u003Ca href=\"https:\u002F\u002Fglama.ai\u002Fmcp\u002Fservers\u002Fyvjy4csvo1\">\u003Cimg width=\"380\" height=\"200\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FClickHouse_mcp-clickhouse_readme_55e6c7046886.png\" alt=\"mcp-clickhouse MCP 服务器\" \u002F>\u003C\u002Fa>\n\n## 功能特性\n\n### ClickHouse 工具\n\n* `run_query`\n  * 在您的 ClickHouse 集群上执行 SQL 查询。\n  * 输入：`query`（字符串）：要执行的 SQL 查询。\n  * 默认情况下，查询以只读模式运行（`CLICKHOUSE_ALLOW_WRITE_ACCESS=false`），但如有需要，可以显式启用写操作。\n\n* `list_databases`\n  * 列出 ClickHouse 集群上的所有数据库。\n\n* `list_tables`\n  * 分页列出某个数据库中的表。\n  * 必需输入：`database`（字符串）。\n  * 可选输入：\n    * `like` \u002F `not_like`（字符串）：对表名应用 `LIKE` 或 `NOT LIKE` 过滤条件。\n    * `page_token`（字符串）：前一次调用返回的标记，用于获取下一页。\n    * `page_size`（整数，默认为 `50`）：每页返回的表数量。\n    * `include_detailed_columns`（布尔值，默认为 `true`）：当设置为 `false` 时，会省略列元数据以获得更轻量级的响应，同时保留完整的 `create_table_query`。\n  * 响应结构：\n    * `tables`：当前页的表对象数组。\n    * `next_page_token`：将此值传回以获取下一页，如果没有更多表则为 `null`。\n    * `total_tables`：符合所提供过滤条件的总表数。\n\n### chDB 工具\n\n* `run_chdb_select_query`\n  * 使用 [chDB](https:\u002F\u002Fgithub.com\u002Fchdb-io\u002Fchdb) 的嵌入式 ClickHouse 引擎执行 SQL 查询。\n  * 输入：`query`（字符串）：要执行的 SQL 查询。\n  * 直接从各种来源（文件、URL、数据库）查询数据，无需 ETL 流程。\n\n### 健康检查端点\n\n当使用 HTTP 或 SSE 传输协议时，健康检查端点位于 `\u002Fhealth`。该端点：\n- 如果服务器运行正常且能够连接到 ClickHouse，则返回 `200 OK` 并附带 ClickHouse 版本信息。\n- 如果服务器无法连接到 ClickHouse，则返回 `503 服务不可用`。\n\n示例：\n```bash\ncurl http:\u002F\u002Flocalhost:8000\u002Fhealth\n# 响应：OK - 已连接到 ClickHouse 24.3.1\n```\n\n## 安全性\n\n### HTTP\u002FSSE 传输的认证\n\n在使用 HTTP 或 SSE 传输时，**默认需要认证**。而默认的 `stdio` 传输不需要认证，因为它仅通过标准输入输出进行通信。\n\n#### 设置认证\n\n1. 生成一个安全令牌（可以是任意随机字符串）：\n   ```bash\n   # 使用 uuidgen（macOS\u002FLinux）\n   uuidgen\n\n   # 使用 openssl\n   openssl rand -hex 32\n   ```\n\n2. 使用该令牌配置服务器：\n   ```bash\n   export CLICKHOUSE_MCP_AUTH_TOKEN=\"您生成的令牌\"\n   ```\n\n3. 配置您的 MCP 客户端，在请求中包含该令牌：\n\n   对于使用 HTTP\u002FSSE 传输的 Claude Desktop：\n   ```json\n   {\n     \"mcpServers\": {\n       \"mcp-clickhouse\": {\n         \"url\": \"http:\u002F\u002F127.0.0.1:8000\",\n         \"headers\": {\n           \"Authorization\": \"Bearer 您生成的令牌\"\n         }\n       }\n     }\n   }\n   ```\n\n   对于命令行工具：\n   ```bash\n   curl -H \"Authorization: Bearer 您生成的令牌\" http:\u002F\u002Flocalhost:8000\u002Fhealth\n   ```\n\n#### 开发模式（禁用认证）\n\n仅限本地开发和测试时，可以通过以下设置禁用认证：\n```bash\nexport CLICKHOUSE_MCP_AUTH_DISABLED=true\n```\n\n**警告：** 请仅在本地开发时使用此设置。切勿在服务器暴露于任何网络时禁用认证。\n\n## 配置\n\n该 MCP 服务器同时支持 ClickHouse 和 chDB。您可以根据需求启用其中一种或两种。\n\n1. 打开位于以下位置的 Claude Desktop 配置文件：\n   * macOS：`~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json`\n   * Windows：`%APPDATA%\u002FClaude\u002Fclaude_desktop_config.json`\n\n2. 添加以下内容：\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-clickhouse\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--with\",\n        \"mcp-clickhouse\",\n        \"--python\",\n        \"3.10\",\n        \"mcp-clickhouse\"\n      ],\n      \"env\": {\n        \"CLICKHOUSE_HOST\": \"\u003Cclickhouse-host>\",\n        \"CLICKHOUSE_PORT\": \"\u003Cclickhouse-port>\",\n        \"CLICKHOUSE_USER\": \"\u003Cclickhouse-user>\",\n        \"CLICKHOUSE_PASSWORD\": \"\u003Cclickhouse-password>\",\n        \"CLICKHOUSE_ROLE\": \"\u003Cclickhouse-role>\",\n        \"CLICKHOUSE_SECURE\": \"true\",\n        \"CLICKHOUSE_VERIFY\": \"true\",\n        \"CLICKHOUSE_CONNECT_TIMEOUT\": \"30\",\n        \"CLICKHOUSE_SEND_RECEIVE_TIMEOUT\": \"30\"\n      }\n    }\n  }\n}\n```\n\n更新环境变量以指向您自己的 ClickHouse 服务。\n\n或者，如果您想使用 [ClickHouse SQL Playground](https:\u002F\u002Fsql.clickhouse.com\u002F) 进行试用，可以使用以下配置：\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-clickhouse\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--with\",\n        \"mcp-clickhouse\",\n        \"--python\",\n        \"3.10\",\n        \"mcp-clickhouse\"\n      ],\n      \"env\": {\n        \"CLICKHOUSE_HOST\": \"sql-clickhouse.clickhouse.com\",\n        \"CLICKHOUSE_PORT\": \"8443\",\n        \"CLICKHOUSE_USER\": \"demo\",\n        \"CLICKHOUSE_PASSWORD\": \"\",\n        \"CLICKHOUSE_SECURE\": \"true\",\n        \"CLICKHOUSE_VERIFY\": \"true\",\n        \"CLICKHOUSE_CONNECT_TIMEOUT\": \"30\",\n        \"CLICKHOUSE_SEND_RECEIVE_TIMEOUT\": \"30\"\n      }\n    }\n  }\n}\n```\n\n对于 chDB（嵌入式 ClickHouse 引擎），添加以下配置：\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-clickhouse\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--with\",\n        \"mcp-clickhouse\",\n        \"--python\",\n        \"3.10\",\n        \"mcp-clickhouse\"\n      ],\n      \"env\": {\n        \"CHDB_ENABLED\": \"true\",\n        \"CLICKHOUSE_ENABLED\": \"false\",\n        \"CHDB_DATA_PATH\": \"\u002Fpath\u002Fto\u002Fchdb\u002Fdata\"\n      }\n    }\n  }\n}\n```\n\n您也可以同时启用 ClickHouse 和 chDB：\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-clickhouse\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--with\",\n        \"mcp-clickhouse\",\n        \"--python\",\n        \"3.10\",\n        \"mcp-clickhouse\"\n      ],\n      \"env\": {\n        \"CLICKHOUSE_HOST\": \"\u003Cclickhouse-host>\",\n        \"CLICKHOUSE_PORT\": \"\u003Cclickhouse-port>\",\n        \"CLICKHOUSE_USER\": \"\u003Cclickhouse-user>\",\n        \"CLICKHOUSE_PASSWORD\": \"\u003Cclickhouse-password>\",\n        \"CLICKHOUSE_SECURE\": \"true\",\n        \"CLICKHOUSE_VERIFY\": \"true\",\n        \"CLICKHOUSE_CONNECT_TIMEOUT\": \"30\",\n        \"CLICKHOUSE_SEND_RECEIVE_TIMEOUT\": \"30\",\n        \"CHDB_ENABLED\": \"true\",\n        \"CHDB_DATA_PATH\": \"\u002Fpath\u002Fto\u002Fchdb\u002Fdata\"\n      }\n    }\n  }\n}\n```\n\n3. 找到 `uv` 的命令条目，并将其替换为 `uv` 可执行文件的绝对路径。这样可以确保启动服务器时使用正确的 `uv` 版本。在 Mac 上，您可以使用 `which uv` 查找该路径。\n\n4. 重启 Claude Desktop 以使更改生效。\n\n### 可选写入权限\n\n默认情况下，此 MCP 强制执行只读查询，以防止在探索过程中发生意外的数据变更。要允许 DDL 或 INSERT\u002FUPDATE 语句，请将 `CLICKHOUSE_ALLOW_WRITE_ACCESS` 环境变量设置为 `true`。如果 ClickHouse 实例本身禁止写入操作，服务器仍会保持只读模式。\n\n### 破坏性操作保护\n\n即使启用了写入权限（`CLICKHOUSE_ALLOW_WRITE_ACCESS=true`），破坏性操作（DROP TABLE、DROP DATABASE、DROP VIEW、DROP DICTIONARY、TRUNCATE TABLE）也需要额外的确认标志才能执行，以确保安全。这可以防止在 AI 探索过程中意外删除数据。\n\n要启用破坏性操作，请同时设置以下两个标志：\n```json\n\"env\": {\n  \"CLICKHOUSE_ALLOW_WRITE_ACCESS\": \"true\",\n  \"CLICKHOUSE_ALLOW_DROP\": \"true\"\n}\n```\n\n这种两层机制确保了意外执行 DROP 操作的可能性极低：\n- **写入操作**（INSERT、UPDATE、CREATE）需要 `CLICKHOUSE_ALLOW_WRITE_ACCESS=true`\n- **破坏性操作**（DROP、TRUNCATE）还需要 `CLICKHOUSE_ALLOW_DROP=true`\n\n### 不使用 uv 运行（使用系统 Python）\n\n如果您希望使用系统 Python 安装而不是 uv，可以直接从 PyPI 安装该包并运行：\n\n1. 使用 pip 安装该包：\n   ```bash\n   python3 -m pip install mcp-clickhouse\n   ```\n\n   要升级到最新版本：\n   ```bash\n   python3 -m pip install --upgrade mcp-clickhouse\n   ```\n\n2. 更新您的 Claude Desktop 配置以直接使用 Python：\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-clickhouse\": {\n      \"command\": \"python3\",\n      \"args\": [\n        \"-m\",\n        \"mcp_clickhouse.main\"\n      ],\n      \"env\": {\n        \"CLICKHOUSE_HOST\": \"\u003Cclickhouse-host>\",\n        \"CLICKHOUSE_PORT\": \"\u003Cclickhouse-port>\",\n        \"CLICKHOUSE_USER\": \"\u003Cclickhouse-user>\",\n        \"CLICKHOUSE_PASSWORD\": \"\u003Cclickhouse-password>\",\n        \"CLICKHOUSE_SECURE\": \"true\",\n        \"CLICKHOUSE_VERIFY\": \"true\",\n        \"CLICKHOUSE_CONNECT_TIMEOUT\": \"30\",\n        \"CLICKHOUSE_SEND_RECEIVE_TIMEOUT\": \"30\"\n      }\n    }\n  }\n}\n```\n\n或者，您也可以直接使用已安装的脚本：\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-clickhouse\": {\n      \"command\": \"mcp-clickhouse\",\n      \"env\": {\n        \"CLICKHOUSE_HOST\": \"\u003Cclickhouse-host>\",\n        \"CLICKHOUSE_PORT\": \"\u003Cclickhouse-port>\",\n        \"CLICKHOUSE_USER\": \"\u003Cclickhouse-user>\",\n        \"CLICKHOUSE_PASSWORD\": \"\u003Cclickhouse-password>\",\n        \"CLICKHOUSE_SECURE\": \"true\",\n        \"CLICKHOUSE_VERIFY\": \"true\",\n        \"CLICKHOUSE_CONNECT_TIMEOUT\": \"30\",\n        \"CLICKHOUSE_SEND_RECEIVE_TIMEOUT\": \"30\"\n      }\n    }\n  }\n}\n```\n\n注意：请确保使用 Python 可执行文件或 `mcp-clickhouse` 脚本的完整路径，如果它们不在您的系统 PATH 中。您可以使用以下命令找到路径：\n- `which python3` 查找 Python 可执行文件\n- `which mcp-clickhouse` 查找已安装的脚本\n\n## 自定义中间件\n\n您可以在不修改源代码的情况下向 MCP 服务器添加自定义中间件。FastMCP 提供了一个中间件系统，允许您拦截和处理 MCP 协议消息（工具调用、资源读取、提示等）。\n\n### 使用方法\n\n1. 创建一个 Python 模块，包含继承自 `Middleware` 的中间件类以及一个 `setup_middleware(mcp)` 函数：\n\n```python\n# my_middleware.py\nimport logging\nfrom fastmcp.server.middleware import Middleware, MiddlewareContext, CallNext\n\nlogger = logging.getLogger(\"my-middleware\")\n\nclass LoggingMiddleware(Middleware):\n    \"\"\"记录所有工具调用。\"\"\"\n    \n    async def on_call_tool(self, context: MiddlewareContext, call_next: CallNext):\n        tool_name = context.message.name if hasattr(context.message, 'name') else 'unknown'\n        logger.info(f\"调用工具：{tool_name}\")\n        result = await call_next(context)\n        logger.info(f\"工具 {tool_name} 执行完毕\")\n        return result\n\ndef setup_middleware(mcp):\n    \"\"\"将中间件注册到 MCP 服务器。\"\"\"\n    mcp.add_middleware(LoggingMiddleware())\n```\n\n2. 将 `MCP_MIDDLEWARE_MODULE` 环境变量设置为模块名称（不带 `.py` 后缀）：\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-clickhouse\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--with\", \"mcp-clickhouse\", \"--python\", \"3.10\", \"mcp-clickhouse\"],\n      \"env\": {\n        \"CLICKHOUSE_HOST\": \"\u003Cclickhouse-host>\",\n        \"CLICKHOUSE_USER\": \"\u003Cclickhouse-user>\",\n        \"CLICKHOUSE_PASSWORD\": \"\u003Cclickhouse-password>\",\n        \"MCP_MIDDLEWARE_MODULE\": \"my_middleware\"\n      }\n    }\n  }\n}\n```\n\n3. 确保您的中间件模块位于 Python 的导入路径中（例如，在 MCP 服务器运行的同一目录下，或作为包安装）。\n\n### 中间件示例\n\n`example_middleware.py` 中提供了一个示例中间件模块，展示了常见模式：\n- 记录所有 MCP 请求\n- 专门记录工具调用\n- 测量请求处理时间\n\n要使用示例：\n```json\n\"env\": {\n  \"MCP_MIDDLEWARE_MODULE\": \"example_middleware\"\n}\n```\n\n### 中间件功能\n\n`Middleware` 基类提供了针对不同 MCP 操作的钩子：\n\n- `on_message(context, call_next)` - 对所有消息调用\n- `on_request(context, call_next)` - 对所有请求调用\n- `on_notification(context, call_next)` - 对所有通知调用\n- `on_call_tool(context, call_next)` - 在执行工具时调用\n- `on_read_resource(context, call_next)` - 在读取资源时调用\n- `on_get_prompt(context, call_next)` - 在获取提示时调用\n- `on_list_tools(context, call_next)` - 在列出工具时调用\n- `on_list_resources(context, call_next)` - 在列出资源时调用\n- `on_list_resource_templates(context, call_next)` - 在列出资源模板时调用\n- `on_list_prompts(context, call_next)` - 在列出提示时调用\n\n每个钩子都会接收到一个包含消息和元数据的 `MiddlewareContext` 对象，以及一个用于继续处理流程的 `call_next` 函数。\n\n### 通过上下文状态动态配置客户端\n\n中间件可以使用 `CLIENT_CONFIG_OVERRIDES_KEY` 上下文状态键，根据每个请求覆盖 ClickHouse 客户端配置。服务器会将这些覆盖与来自环境变量的基线配置合并。\n\n```python\nfrom fastmcp.server.dependencies import get_context\nfrom mcp_clickhouse.mcp_server import CLIENT_CONFIG_OVERRIDES_KEY\n\nctx = get_context()\nctx.set_state(CLIENT_CONFIG_OVERRIDES_KEY, {\n    \"connect_timeout\": 60,\n    \"send_receive_timeout\": 120\n})\n```\n\n这使得一些高级用法成为可能，例如动态调整超时时间、按租户路由，或为每个用户设置不同的连接参数。\n\n## 开发\n\n1. 在 `test-services` 目录下运行 `docker compose up -d` 来启动 ClickHouse 集群。\n\n2. 将以下变量添加到仓库根目录下的 `.env` 文件中。\n\n*注意：在此上下文中使用 `default` 用户仅用于本地开发目的。*\n\n```bash\nCLICKHOUSE_HOST=localhost\nCLICKHOUSE_PORT=8123\nCLICKHOUSE_USER=default\nCLICKHOUSE_PASSWORD=clickhouse\n```\n\n3. 运行 `uv sync` 来安装依赖项。要安装 `uv`，请按照 [这里](https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002F) 的说明进行操作。然后执行 `source .venv\u002Fbin\u002Factivate`。\n\n4. 为了便于使用 MCP Inspector 进行测试，运行 `fastmcp dev mcp_clickhouse\u002Fmcp_server.py` 来启动 MCP 服务器。\n\n5. 若要使用 HTTP 传输和健康检查端点进行测试：\n   ```bash\n   # 对于开发，禁用身份验证\n   CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_DISABLED=true python -m mcp_clickhouse.main\n\n   # 或者启用身份验证（先生成令牌）\n   CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_TOKEN=\"your-token\" python -m mcp_clickhouse.main\n\n   # 然后在另一个终端中：\n   # 如果已禁用身份验证：\n   curl http:\u002F\u002Flocalhost:8000\u002Fhealth\n\n   # 如果启用身份验证：\n   curl -H \"Authorization: Bearer your-token\" http:\u002F\u002Flocalhost:8000\u002Fhealth\n   ```\n\n### 环境变量\n\n以下环境变量用于配置 ClickHouse 和 chDB 的连接：\n\n#### ClickHouse 变量\n\n##### 必需变量\n\n* `CLICKHOUSE_HOST`：您的 ClickHouse 服务器的主机名\n* `CLICKHOUSE_USER`：用于身份验证的用户名\n* `CLICKHOUSE_PASSWORD`：用于身份验证的密码\n\n> [!CAUTION]\n> 务必像对待任何连接到您数据库的外部客户端一样对待您的 MCP 数据库用户，仅授予其正常运行所需的最低权限。应始终严格避免使用默认或管理员用户。\n\n##### 可选变量\n\n* `CLICKHOUSE_PORT`：您的 ClickHouse 服务器的端口号\n  * 默认值：如果启用了 HTTPS，则为 `8443`；如果未启用，则为 `8123`。\n  * 通常无需设置，除非使用非标准端口。\n* `CLICKHOUSE_ROLE`：用于身份验证的角色\n  * 默认值：无\n  * 如果您的用户需要特定角色，请设置此变量。\n* `CLICKHOUSE_SECURE`：启用或禁用 HTTPS 连接\n  * 默认值：`\"true\"`\n  * 对于非安全连接，将其设置为 `\"false\"`。\n* `CLICKHOUSE_VERIFY`：启用或禁用 SSL 证书验证\n  * 默认值：`\"true\"`\n  * 将其设置为 `\"false\"` 可以禁用证书验证（不建议在生产环境中使用）。\n  * TLS 证书：该包通过 `truststore` 使用您的操作系统信任存储来验证 TLS 证书。我们在启动时调用 `truststore.inject_into_ssl()`，以确保正确处理证书。只有在发生意外错误时，才会回退到 Python 的默认 SSL 行为。\n* `CLICKHOUSE_CONNECT_TIMEOUT`：连接超时时间（秒）\n  * 默认值：`\"30\"`\n  * 如果遇到连接超时问题，请增加此值。\n* `CLICKHOUSE_SEND_RECEIVE_TIMEOUT`：发送\u002F接收超时时间（秒）\n  * 默认值：`\"300\"`\n  * 对于长时间运行的查询，可以增加此值。\n* `CLICKHOUSE_DATABASE`：默认使用的数据库\n  * 默认值：无（使用服务器默认值）。\n  * 设置此变量可自动连接到特定数据库。\n* `CLICKHOUSE_MCP_SERVER_TRANSPORT`：设置 MCP 服务器的传输方式。\n  * 默认值：`\"stdio\"`\n  * 有效选项：`\"stdio\"`、`\"http\"`、`\"sse\"`。这在使用 MCP Inspector 等工具进行本地开发时非常有用。\n* `CLICKHOUSE_MCP_BIND_HOST`：当使用 HTTP 或 SSE 传输时，MCP 服务器绑定的主机\n  * 默认值：`\"127.0.0.1\"`\n  * 设置为 `\"0.0.0.0\"` 可绑定到所有网络接口（适用于 Docker 或远程访问）。\n  * 仅在传输方式为 `\"http\"` 或 `\"sse\"` 时使用。\n* `CLICKHOUSE_MCP_BIND_PORT`：当使用 HTTP 或 SSE 传输时，MCP 服务器绑定的端口\n  * 默认值：`\"8000\"`\n  * 仅在传输方式为 `\"http\"` 或 `\"sse\"` 时使用。\n* `CLICKHOUSE_MCP_QUERY_TIMEOUT`：SELECT 工具的超时时间（秒）\n  * 默认值：`\"30\"`\n  * 如果遇到 `Query timed out after ...` 错误，对于复杂查询可以适当延长此时间。\n* `CLICKHOUSE_MCP_AUTH_TOKEN`：用于 HTTP\u002FSSE 传输的身份验证令牌\n  * 默认值：无\n  * **必须**在使用 HTTP 或 SSE 传输时提供（除非 `CLICKHOUSE_MCP_AUTH_DISABLED=true`）。\n  * 可以使用 `uuidgen` 或 `openssl rand -hex 32` 生成令牌。\n  * 客户端必须在 `Authorization: Bearer \u003Ctoken>` 头中发送此令牌。\n* `CLICKHOUSE_MCP_AUTH_DISABLED`：禁用 HTTP\u002FSSE 传输的身份验证\n  * 默认值：`\"false`（身份验证已启用）。\n  * 设置为 `\"true\"` 只能在本地开发\u002F测试时禁用身份验证。\n  * **警告：** 仅限于本地开发使用。切勿在网络环境中启用此功能。\n* `CLICKHOUSE_ENABLED`：启用或禁用 ClickHouse 功能\n  * 默认值：`\"true\"`\n  * 设置为 `\"false\"` 可以在仅使用 chDB 时禁用 ClickHouse 工具。\n* `CLICKHOUSE_ALLOW_WRITE_ACCESS`：允许写操作（DDL 和 DML）\n  * 默认值：`\"false\"`\n  * 设置为 `\"true\"` 可以允许 DDL（CREATE、ALTER、DROP）和 DML（INSERT、UPDATE、DELETE）操作。\n  * 当禁用时（默认），查询会以 `readonly=1` 设置运行，以防止数据修改。\n* `CLICKHOUSE_ALLOW_DROP`：允许破坏性操作（DROP TABLE、DROP DATABASE、DROP VIEW、DROP DICTIONARY、TRUNCATE TABLE）\n  * 默认值：`\"false\"`\n  * 仅在同时设置了 `CLICKHOUSE_ALLOW_WRITE_ACCESS=true` 时生效。\n  * 设置为 `\"true\"` 可以明确允许 DROP 和 TRUNCATE 等破坏性操作。\n  * 这是一个安全功能，可在 AI 探索过程中防止意外删除数据。\n\n#### 中间件变量\n\n* `MCP_MIDDLEWARE_MODULE`：包含自定义中间件的 Python 模块名称，用于注入到 MCP 服务器中\n  * 默认值：无（未加载中间件）。\n  * 设置为您中间件模块的名称（不带 `.py` 扩展名）。\n  * 该模块必须提供一个 `setup_middleware(mcp)` 函数。\n  * 有关详细信息和示例，请参阅 [自定义中间件](#custom-middleware)。\n\n#### chDB 变量\n\n* `CHDB_ENABLED`：启用或禁用 chDB 功能\n  * 默认值：`\"false\"`\n  * 设置为 `\"true\"` 可以启用 chDB 工具。\n* `CHDB_DATA_PATH`：chDB 数据目录的路径\n  * 默认值：`\":memory:\"`（内存数据库）。\n  * 使用 `:memory:` 可以创建内存数据库。\n  * 使用文件路径可以实现持久化存储（例如 `\u002Fpath\u002Fto\u002Fchdb\u002Fdata`）。\n\n#### 示例配置\n\n用于 Docker 的本地开发：\n\n```env\n# 必需变量\nCLICKHOUSE_HOST=localhost\nCLICKHOUSE_USER=default\nCLICKHOUSE_PASSWORD=clickhouse\n\n# 可选：覆盖本地开发的默认值\nCLICKHOUSE_SECURE=false  # 自动使用 8123 端口\nCLICKHOUSE_VERIFY=false\n```\n\n用于 ClickHouse Cloud：\n\n```env\n# 必需变量\nCLICKHOUSE_HOST=your-instance.clickhouse.cloud\nCLICKHOUSE_USER=default\nCLICKHOUSE_PASSWORD=your-password\n\n# 可选：这些使用安全默认值\n# CLICKHOUSE_SECURE=true  # 自动使用 8443 端口\n\n# CLICKHOUSE_DATABASE=您的数据库\n```\n\n适用于 ClickHouse SQL Playground：\n\n```env\nCLICKHOUSE_HOST=sql-clickhouse.clickhouse.com\nCLICKHOUSE_USER=demo\nCLICKHOUSE_PASSWORD=\n# 使用安全默认设置（HTTPS，端口 8443）\n```\n\n仅使用 chDB（内存中）：\n\n```env\n# chDB 配置\nCHDB_ENABLED=true\nCLICKHOUSE_ENABLED=false\n# CHDB_DATA_PATH 默认为 :memory:\n```\n\n使用持久化存储的 chDB：\n\n```env\n# chDB 配置\nCHDB_ENABLED=true\nCLICKHOUSE_ENABLED=false\nCHDB_DATA_PATH=\u002Fpath\u002Fto\u002Fchdb\u002Fdata\n```\n\n用于 MCP Inspector 或通过 HTTP 传输进行远程访问：\n\n```env\nCLICKHOUSE_HOST=localhost\nCLICKHOUSE_USER=default\nCLICKHOUSE_PASSWORD=clickhouse\nCLICKHOUSE_MCP_SERVER_TRANSPORT=http\nCLICKHOUSE_MCP_BIND_HOST=0.0.0.0  # 绑定到所有接口\nCLICKHOUSE_MCP_BIND_PORT=4200  # 自定义端口（默认：8000）\nCLICKHOUSE_MCP_AUTH_TOKEN=您生成的令牌  # HTTP\u002FSSE 需要\n```\n\n用于本地开发且禁用身份验证的 HTTP 传输：\n\n```env\nCLICKHOUSE_HOST=localhost\nCLICKHOUSE_USER=default\nCLICKHOUSE_PASSWORD=clickhouse\nCLICKHOUSE_MCP_SERVER_TRANSPORT=http\nCLICKHOUSE_MCP_AUTH_DISABLED=true  # 仅限本地开发！\n```\n\n使用 HTTP 传输时，服务器将在配置的端口上运行（默认为 8000）。例如，按照上述配置：\n- MCP 端点：`http:\u002F\u002Flocalhost:4200\u002Fmcp`\n- 健康检查：`http:\u002F\u002Flocalhost:4200\u002Fhealth`\n\n您可以将这些变量设置在环境变量中、`.env` 文件中，或在 Claude Desktop 的配置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-clickhouse\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--with\",\n        \"mcp-clickhouse\",\n        \"--python\",\n        \"3.10\",\n        \"mcp-clickhouse\"\n      ],\n      \"env\": {\n        \"CLICKHOUSE_HOST\": \"\u003Cclickhouse-host>\",\n        \"CLICKHOUSE_USER\": \"\u003Cclickhouse-user>\",\n        \"CLICKHOUSE_PASSWORD\": \"\u003Cclickhouse-password>\",\n        \"CLICKHOUSE_DATABASE\": \"\u003C可选数据库>\",\n        \"CLICKHOUSE_MCP_SERVER_TRANSPORT\": \"stdio\",\n        \"CLICKHOUSE_MCP_BIND_HOST\": \"127.0.0.1\",\n        \"CLICKHOUSE_MCP_BIND_PORT\": \"8000\"\n      }\n    }\n  }\n}\n```\n\n注意：绑定主机和端口设置仅在传输方式设置为 “http” 或 “sse” 时才会生效。\n\n### 运行测试\n\n```bash\nuv sync --all-extras --dev # 安装开发依赖\nuv run ruff check . # 运行代码检查\n\ndocker compose up -d test_services # 启动 ClickHouse\nuv run pytest -v tests\nuv run pytest -v tests\u002Ftest_tool.py # 仅针对 ClickHouse\nuv run pytest -v tests\u002Ftest_chdb_tool.py # 仅针对 chDB\n```\n\n## YouTube 概览\n\n[![YouTube](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FClickHouse_mcp-clickhouse_readme_303b784f736f.jpg)](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=y9biAm_Fkqw)","# mcp-clickhouse 快速上手指南\n\nmcp-clickhouse 是一个专为 ClickHouse 设计的 MCP（Model Context Protocol）服务器，允许 AI 助手直接执行 SQL 查询、管理数据库和表，并支持嵌入式的 chDB 引擎。\n\n## 环境准备\n\n*   **操作系统**: macOS, Linux 或 Windows\n*   **Python 版本**: 推荐 Python 3.10 或更高版本\n*   **依赖管理工具**: 推荐使用 [`uv`](https:\u002F\u002Fgithub.com\u002Fastral-sh\u002Fuv) (自动管理)，或使用系统自带的 `pip`\n*   **ClickHouse 服务**: 需要可访问的 ClickHouse 集群地址，或使用官方提供的 [SQL Playground](https:\u002F\u002Fsql.clickhouse.com\u002F) 进行测试\n*   **客户端**: 已安装并配置好的 Claude Desktop 或其他支持 MCP 的客户端\n\n## 安装步骤\n\n本工具无需单独安装二进制文件，主要通过配置 MCP 客户端来运行。以下以 **Claude Desktop** 为例。\n\n### 1. 获取 uv 路径 (推荐)\n如果使用 `uv` 运行（推荐方式，可自动隔离环境），请先找到其绝对路径：\n```bash\nwhich uv\n# macOS\u002FLinux 示例输出: \u002FUsers\u002Fusername\u002F.local\u002Fbin\u002Fuv\n```\n\n### 2. 配置 Claude Desktop\n打开配置文件：\n*   **macOS**: `~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json`\n*   **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n添加以下配置内容。**注意**：请将 `\u003Cabsolute-path-to-uv>` 替换为第一步中获取的实际路径，并根据你的 ClickHouse 服务修改 `env` 中的连接信息。\n\n#### 方案 A：连接自有 ClickHouse 集群\n```json\n{\n  \"mcpServers\": {\n    \"mcp-clickhouse\": {\n      \"command\": \"\u003Cabsolute-path-to-uv>\",\n      \"args\": [\n        \"run\",\n        \"--with\",\n        \"mcp-clickhouse\",\n        \"--python\",\n        \"3.10\",\n        \"mcp-clickhouse\"\n      ],\n      \"env\": {\n        \"CLICKHOUSE_HOST\": \"\u003Cyour-clickhouse-host>\",\n        \"CLICKHOUSE_PORT\": \"\u003Cyour-clickhouse-port>\",\n        \"CLICKHOUSE_USER\": \"\u003Cyour-clickhouse-user>\",\n        \"CLICKHOUSE_PASSWORD\": \"\u003Cyour-clickhouse-password>\",\n        \"CLICKHOUSE_SECURE\": \"true\",\n        \"CLICKHOUSE_VERIFY\": \"true\",\n        \"CLICKHOUSE_CONNECT_TIMEOUT\": \"30\",\n        \"CLICKHOUSE_SEND_RECEIVE_TIMEOUT\": \"30\"\n      }\n    }\n  }\n}\n```\n\n#### 方案 B：快速体验 (使用 ClickHouse 官方 Playground)\n如果你没有本地集群，可使用此配置直接连接官方演示环境：\n```json\n{\n  \"mcpServers\": {\n    \"mcp-clickhouse\": {\n      \"command\": \"\u003Cabsolute-path-to-uv>\",\n      \"args\": [\n        \"run\",\n        \"--with\",\n        \"mcp-clickhouse\",\n        \"--python\",\n        \"3.10\",\n        \"mcp-clickhouse\"\n      ],\n      \"env\": {\n        \"CLICKHOUSE_HOST\": \"sql-clickhouse.clickhouse.com\",\n        \"CLICKHOUSE_PORT\": \"8443\",\n        \"CLICKHOUSE_USER\": \"demo\",\n        \"CLICKHOUSE_PASSWORD\": \"\",\n        \"CLICKHOUSE_SECURE\": \"true\",\n        \"CLICKHOUSE_VERIFY\": \"true\",\n        \"CLICKHOUSE_CONNECT_TIMEOUT\": \"30\",\n        \"CLICKHOUSE_SEND_RECEIVE_TIMEOUT\": \"30\"\n      }\n    }\n  }\n}\n```\n\n#### 方案 C：仅使用嵌入式 chDB (无需外部集群)\n如果只需分析本地文件或使用嵌入式引擎：\n```json\n{\n  \"mcpServers\": {\n    \"mcp-clickhouse\": {\n      \"command\": \"\u003Cabsolute-path-to-uv>\",\n      \"args\": [\n        \"run\",\n        \"--with\",\n        \"mcp-clickhouse\",\n        \"--python\",\n        \"3.10\",\n        \"mcp-clickhouse\"\n      ],\n      \"env\": {\n        \"CHDB_ENABLED\": \"true\",\n        \"CLICKHOUSE_ENABLED\": \"false\",\n        \"CHDB_DATA_PATH\": \"\u002Ftmp\u002Fchdb_data\"\n      }\n    }\n  }\n}\n```\n\n> **提示**: 如果不想使用 `uv`，也可通过 `pip install mcp-clickhouse` 安装后，将 `command` 改为 `python3` 或 `mcp-clickhouse` 脚本路径（详见原文档 \"Running Without uv\" 部分）。\n\n### 3. 重启客户端\n保存配置文件并完全重启 Claude Desktop 以加载新的 MCP 服务器。\n\n## 基本使用\n\n配置完成后，你可以在对话中直接使用自然语言让 AI 操作 ClickHouse。\n\n### 1. 查看数据库和表\n尝试询问：\n> \"列出所有的数据库。\"\n> \"显示 default 数据库中的所有表。\"\n\n底层将调用 `list_databases` 和 `list_tables` 工具。\n\n### 2. 执行查询\n尝试询问：\n> \"查询 system.clusters 表，看看有哪些节点。\"\n> \"计算 numbers 表中前 1000 个数字的和。\"\n\n底层将调用 `run_query` 工具执行 SQL。\n*   **默认模式**: 只读模式 (`SELECT` 语句)，防止误操作。\n*   **写入模式**: 如需执行 `INSERT` 或 `CREATE`，需在配置中添加 `\"CLICKHOUSE_ALLOW_WRITE_ACCESS\": \"true\"`。\n*   **删除保护**: 如需执行 `DROP` 或 `TRUNCATE`，需同时添加 `\"CLICKHOUSE_ALLOW_DROP\": \"true\"`。\n\n### 3. 使用 chDB 分析本地数据\n如果启用了 chDB，可以直接查询本地文件：\n> \"读取当前目录下的 data.csv 文件并统计行数。\"\n\n底层将调用 `run_chdb_select_query` 工具，无需 ETL 过程。\n\n### 4. 健康检查 (可选)\n如果你通过 HTTP\u002FSSE 模式运行服务器，可以通过以下命令检查状态：\n```bash\ncurl http:\u002F\u002Flocalhost:8000\u002Fhealth\n# 正常响应: OK - Connected to ClickHouse \u003Cversion>\n```\n*(注：默认的 stdio 模式不需要此步骤)*","某电商数据分析师需要在晨会前快速从亿级订单日志中定位昨日异常交易，并生成简要报告。\n\n### 没有 mcp-clickhouse 时\n- 分析师必须手动切换到数据库客户端，编写并调试复杂的 SQL 语句来查询 ClickHouse 集群，过程繁琐且容易出错。\n- 面对成百上千张分表，需要反复执行命令列出数据库和表名，难以通过自然语言快速筛选目标数据表。\n- 将查询结果复制粘贴到 AI 对话框进行解读时，上下文断裂，AI 无法直接结合实时数据给出深度洞察。\n- 每次临时取数都需经历“查文档 - 写代码 - 跑脚本 - 导数据”的长链路，严重拖慢晨会决策效率。\n- 若需验证本地文件数据与线上差异，还得额外搭建 ETL 流程或下载海量数据到本地，耗时耗力。\n\n### 使用 mcp-clickhouse 后\n- 分析师直接在对话中指令 mcp-clickhouse 执行 `run_query`，工具自动以只读模式安全地返回亿级数据的聚合结果。\n- 通过 `list_tables` 配合模糊过滤参数，瞬间锁定包含\"order\"字样的特定业务表，无需记忆冗长的表名。\n- AI 助手调用工具获取实时数据后，立即在同一对话窗口内完成异常检测、归因分析并生成自然语言报告。\n- 整个取数分析过程缩短为几分钟的对话交互，分析师可专注于业务逻辑而非数据提取的技术细节。\n- 利用内置的 chDB 功能，直接对本地 CSV 日志运行 SQL 并与线上数据对比，彻底免去了繁琐的数据搬运过程。\n\nmcp-clickhouse 将原本割裂的数据库操作无缝融入 AI 对话流，让海量数据分析变得像日常聊天一样简单高效。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FClickHouse_mcp-clickhouse_303b784f.jpg","ClickHouse","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002FClickHouse_0330a7b1.png","",null,"feedback@clickhouse.com","ClickHouseDB","https:\u002F\u002Fclickhouse.com","https:\u002F\u002Fgithub.com\u002FClickHouse",[23,27],{"name":24,"color":25,"percentage":26},"Python","#3572A5",98.5,{"name":28,"color":29,"percentage":30},"Dockerfile","#384d54",1.5,747,175,"2026-04-06T02:42:01","Apache-2.0",2,"Linux, macOS, Windows","未说明",{"notes":39,"python":40,"dependencies":41},"该工具是一个 ClickHouse MCP 服务器，支持通过 uv 或系统 Python 运行。默认情况下需要配置 ClickHouse 连接信息（主机、端口、用户、密码等），也可选择使用嵌入式的 chDB 引擎无需外部数据库。HTTP\u002FSSE 传输模式默认需要身份验证令牌，本地开发可禁用但生产环境严禁禁用。支持自定义中间件扩展功能。写操作和破坏性操作（如 DROP）需显式开启环境变量保护。","3.10+",[6,42,43,44],"uv","chdb (可选)","fastmcp",[46,47],"数据工具","插件","ready","2026-03-27T02:49:30.150509","2026-04-09T21:36:22.924581",[52,57,62,67,72,77],{"id":53,"question_zh":54,"answer_zh":55,"source_url":56},26673,"如何在 Cursor 编辑器中配置并启动 mcp-clickhouse 服务器？","由于环境变量传递问题，建议创建一个 Bash 包装脚本来设置变量并启动服务器。具体步骤如下：\n1. 创建脚本 `.cursor\u002Fmcp_clickhouse_wrapper.sh`：\n```bash\n#!\u002Fbin\u002Fbash\nexport CLICKHOUSE_HOST=xxxx\nexport CLICKHOUSE_PASSWORD=xxx\nexport CLICKHOUSE_USER=xxx\nexport CLICKHOUSE_PORT=8443\nexport CLICKHOUSE_SECURE=True\nexport CLICKHOUSE_CONNECT_TIMEOUT=30\nexport CLICKHOUSE_SEND_RECEIVE_TIMEOUT=30\nexec uv run --with mcp-clickhouse --python 3.13 mcp-clickhouse\n```\n2. 在 `.\u002Fcursor\u002Fmcp.json` 中配置命令：\n```json\n{\n    \"mcpServers\": {\n        \"clickhouse\": {\n            \"command\": \"bash .\u002F.cursor\u002Fmcp_clickhouse_wrapper.sh\"\n        }\n    }\n}\n```","https:\u002F\u002Fgithub.com\u002FClickHouse\u002Fmcp-clickhouse\u002Fissues\u002F16",{"id":58,"question_zh":59,"answer_zh":60,"source_url":61},26674,"连接 ClickHouse Cloud 时遇到 SSL 证书验证错误（CERTIFICATE_VERIFY_FAILED）怎么办？","这通常是因为未正确启用安全连接。请确保在环境变量中显式设置 `CLICKHOUSE_SECURE=True`。如果是在 Cursor 中使用，请参考上述 Bash 包装脚本的配置方法，确保包含 `export CLICKHOUSE_SECURE=True` 这一行。此外，确认端口设置为 8443（默认 HTTPS 端口）而非 8123。","https:\u002F\u002Fgithub.com\u002FClickHouse\u002Fmcp-clickhouse\u002Fissues\u002F10",{"id":63,"question_zh":64,"answer_zh":65,"source_url":66},26675,"当数据库表数量过多（超过 100 张）导致 list_tables 工具崩溃或断开连接时如何解决？","这是由于返回的元数据负载过大导致的。目前的解决方案包括：\n1. 等待官方合并支持分页（pagination）和元数据裁剪的 PR（如 PR #92）。\n2. 临时避免在大型 Schema 上直接调用无限制的 `list_tables`。\n3. 开发者已在新的实现中添加了修剪重型列元数据的选项，并计划限制单次获取的表数量（例如配置为 100-200 张）。建议关注最新版本更新以获取此修复。","https:\u002F\u002Fgithub.com\u002FClickHouse\u002Fmcp-clickhouse\u002Fissues\u002F25",{"id":68,"question_zh":69,"answer_zh":70,"source_url":71},26676,"list_tables 工具的过滤参数（like\u002Fnot_like）为什么不生效？","这是一个参数格式问题。在 MCP Inspector 或调用工具时，如果过滤值包含通配符（如 `%`），必须用双引号将整个字符串包裹起来。\n错误写法：`host_source%`\n正确写法：`\"host_source%\"`\n如果不加引号，服务器可能无法正确解析过滤条件，从而返回所有表。","https:\u002F\u002Fgithub.com\u002FClickHouse\u002Fmcp-clickhouse\u002Fissues\u002F61",{"id":73,"question_zh":74,"answer_zh":75,"source_url":76},26677,"如何启用写入权限（如执行 INSERT 或 DDL 操作），默认似乎是只读的？","默认情况下为了安全起见是只读的。如果需要写入权限，可以通过以下方式解决：\n1. 等待官方版本更新，维护者已计划添加可选的写入访问支持。\n2. 临时方案是使用社区 Fork 版本（如 mcp-timeplus），其中添加了 `READONLY` 标志。将该标志设置为 `false` 即可允许执行 DDL 或 INSERT 语句。\n注意：在生产环境中开启写入权限需确保 Docker 容器等运行环境的安全性。","https:\u002F\u002Fgithub.com\u002FClickHouse\u002Fmcp-clickhouse\u002Fissues\u002F24",{"id":78,"question_zh":79,"answer_zh":80,"source_url":81},26678,"运行时报错 'TypeError: FastMCP.__init__() got an unexpected keyword argument dependencies' 是什么原因？","这是因为 `mcp-clickhouse` 依赖的 `FastMCP` 库版本不兼容。旧版代码传递了 `dependencies` 参数，但新版 FastMCP 已移除该参数支持。\n解决方案：\n请升级 `mcp-clickhouse` 到最新发布的 PyPI 版本，维护者已经发布修复了此兼容性问题的新版本。运行以下命令更新：\n`pip install --upgrade mcp-clickhouse`\n或者如果使用 uv，请重新运行安装命令以拉取最新包。","https:\u002F\u002Fgithub.com\u002FClickHouse\u002Fmcp-clickhouse\u002Fissues\u002F106",[83,88],{"id":84,"version":85,"summary_zh":86,"released_at":87},171875,"v0.2.0","## 变更内容\n* 由 @joe-clickhouse 在 https:\u002F\u002Fgithub.com\u002FClickHouse\u002Fmcp-clickhouse\u002Fpull\u002F113 中添加了对 HTTP 和 SSE 传输协议的身份验证支持。\n\n\n**完整变更日志**: https:\u002F\u002Fgithub.com\u002FClickHouse\u002Fmcp-clickhouse\u002Fcompare\u002Fv0.1.13...v0.2.0","2026-01-28T19:55:40",{"id":89,"version":90,"summary_zh":91,"released_at":92},171876,"v0.1.13","## 变更内容\n* 今后将同步 GitHub 发布与 PyPI 发布\n* 之前版本请参阅 [PyPI 发布历史](https:\u002F\u002Fpypi.org\u002Fproject\u002Fmcp-clickhouse\u002F#history)\n\n## v0.1.13 的新特性\n- 在只读保护下对 ClickHouse 集群执行 SQL 查询\n- 支持分页、过滤及详细元数据的数据库和表列表展示\n- [chDB](https:\u002F\u002Fgithub.com\u002Fchdb-io\u002Fchdb) 支持：直接使用嵌入式 ClickHouse 引擎查询文件、URL 和数据库（无需 ETL）\n- 兼容 ClickHouse Cloud、自托管实例以及本地开发环境\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002FClickHouse\u002Fmcp-clickhouse\u002Fcommits\u002Fv0.1.13","2025-12-16T16:51:36",[94,106,114,126,135,143],{"id":95,"name":96,"github_repo":97,"description_zh":98,"stars":99,"difficulty_score":100,"last_commit_at":101,"category_tags":102,"status":48},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[103,104,105,46],"Agent","开发框架","图像",{"id":107,"name":108,"github_repo":109,"description_zh":110,"stars":111,"difficulty_score":35,"last_commit_at":112,"category_tags":113,"status":48},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[47,104],{"id":115,"name":116,"github_repo":117,"description_zh":118,"stars":119,"difficulty_score":35,"last_commit_at":120,"category_tags":121,"status":48},2268,"ML-For-Beginners","microsoft\u002FML-For-Beginners","ML-For-Beginners 是由微软推出的一套系统化机器学习入门课程，旨在帮助零基础用户轻松掌握经典机器学习知识。这套课程将学习路径规划为 12 周，包含 26 节精炼课程和 52 道配套测验，内容涵盖从基础概念到实际应用的完整流程，有效解决了初学者面对庞大知识体系时无从下手、缺乏结构化指导的痛点。\n\n无论是希望转型的开发者、需要补充算法背景的研究人员，还是对人工智能充满好奇的普通爱好者，都能从中受益。课程不仅提供了清晰的理论讲解，还强调动手实践，让用户在循序渐进中建立扎实的技能基础。其独特的亮点在于强大的多语言支持，通过自动化机制提供了包括简体中文在内的 50 多种语言版本，极大地降低了全球不同背景用户的学习门槛。此外，项目采用开源协作模式，社区活跃且内容持续更新，确保学习者能获取前沿且准确的技术资讯。如果你正寻找一条清晰、友好且专业的机器学习入门之路，ML-For-Beginners 将是理想的起点。",85052,"2026-04-08T11:03:08",[105,46,122,47,103,123,124,104,125],"视频","其他","语言模型","音频",{"id":127,"name":128,"github_repo":129,"description_zh":130,"stars":131,"difficulty_score":132,"last_commit_at":133,"category_tags":134,"status":48},5784,"funNLP","fighting41love\u002FfunNLP","funNLP 是一个专为中文自然语言处理（NLP）打造的超级资源库，被誉为\"NLP 民工的乐园”。它并非单一的软件工具，而是一个汇集了海量开源项目、数据集、预训练模型和实用代码的综合性平台。\n\n面对中文 NLP 领域资源分散、入门门槛高以及特定场景数据匮乏的痛点，funNLP 提供了“一站式”解决方案。这里不仅涵盖了分词、命名实体识别、情感分析、文本摘要等基础任务的标准工具，还独特地收录了丰富的垂直领域资源，如法律、医疗、金融行业的专用词库与数据集，甚至包含古诗词生成、歌词创作等趣味应用。其核心亮点在于极高的全面性与实用性，从基础的字典词典到前沿的 BERT、GPT-2 模型代码，再到高质量的标注数据和竞赛方案，应有尽有。\n\n无论是刚刚踏入 NLP 领域的学生、需要快速验证想法的算法工程师，还是从事人工智能研究的学者，都能在这里找到急需的“武器弹药”。对于开发者而言，它能大幅减少寻找数据和复现模型的时间；对于研究者，它提供了丰富的基准测试资源和前沿技术参考。funNLP 以开放共享的精神，极大地降低了中文自然语言处理的开发与研究成本，是中文 AI 社区不可或缺的宝藏仓库。",79857,1,"2026-04-08T20:11:31",[124,46,123],{"id":136,"name":137,"github_repo":138,"description_zh":139,"stars":140,"difficulty_score":132,"last_commit_at":141,"category_tags":142,"status":48},5773,"cs-video-courses","Developer-Y\u002Fcs-video-courses","cs-video-courses 是一个精心整理的计算机科学视频课程清单，旨在为自学者提供系统化的学习路径。它汇集了全球知名高校（如加州大学伯克利分校、新南威尔士大学等）的完整课程录像，涵盖从编程基础、数据结构与算法，到操作系统、分布式系统、数据库等核心领域，并深入延伸至人工智能、机器学习、量子计算及区块链等前沿方向。\n\n面对网络上零散且质量参差不齐的教学资源，cs-video-courses 解决了学习者难以找到成体系、高难度大学级别课程的痛点。该项目严格筛选内容，仅收录真正的大学层级课程，排除了碎片化的简短教程或商业广告，确保用户能接触到严谨的学术内容。\n\n这份清单特别适合希望夯实计算机基础的开发者、需要补充特定领域知识的研究人员，以及渴望像在校生一样系统学习计算机科学的自学者。其独特的技术亮点在于分类极其详尽，不仅包含传统的软件工程与网络安全，还细分了生成式 AI、大语言模型、计算生物学等新兴学科，并直接链接至官方视频播放列表，让用户能一站式获取高质量的教育资源，免费享受世界顶尖大学的课堂体验。",79792,"2026-04-08T22:03:59",[123,105,46,104],{"id":144,"name":145,"github_repo":146,"description_zh":147,"stars":148,"difficulty_score":100,"last_commit_at":149,"category_tags":150,"status":48},2181,"OpenHands","OpenHands\u002FOpenHands","OpenHands 是一个专注于 AI 驱动开发的开源平台，旨在让智能体（Agent）像人类开发者一样理解、编写和调试代码。它解决了传统编程中重复性劳动多、环境配置复杂以及人机协作效率低等痛点，通过自动化流程显著提升开发速度。\n\n无论是希望提升编码效率的软件工程师、探索智能体技术的研究人员，还是需要快速原型验证的技术团队，都能从中受益。OpenHands 提供了灵活多样的使用方式：既可以通过命令行（CLI）或本地图形界面在个人电脑上轻松上手，体验类似 Devin 的流畅交互；也能利用其强大的 Python SDK 自定义智能体逻辑，甚至在云端大规模部署上千个智能体并行工作。\n\n其核心技术亮点在于模块化的软件智能体 SDK，这不仅构成了平台的引擎，还支持高度可组合的开发模式。此外，OpenHands 在 SWE-bench 基准测试中取得了 77.6% 的优异成绩，证明了其解决真实世界软件工程问题的能力。平台还具备完善的企业级功能，支持与 Slack、Jira 等工具集成，并提供细粒度的权限管理，适合从个人开发者到大型企业的各类用户场景。",70879,"2026-04-09T11:20:38",[124,103,104,47]]