{"id":26127013,"url":"https://github.com/ClickHouse/mcp-clickhouse","last_synced_at":"2025-03-10T18:02:23.862Z","repository":{"id":271576392,"uuid":"908231244","full_name":"ClickHouse/mcp-clickhouse","owner":"ClickHouse","description":null,"archived":false,"fork":false,"pushed_at":"2025-02-27T23:29:17.000Z","size":54,"stargazers_count":60,"open_issues_count":2,"forks_count":14,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-02-28T08:12:41.139Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ClickHouse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-25T14:15:46.000Z","updated_at":"2025-02-27T23:29:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"59dcad98-9ab4-4335-8a39-d0eeaf1b1569","html_url":"https://github.com/ClickHouse/mcp-clickhouse","commit_stats":null,"previous_names":["clickhouse/mcp-clickhouse"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClickHouse%2Fmcp-clickhouse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClickHouse%2Fmcp-clickhouse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClickHouse%2Fmcp-clickhouse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClickHouse%2Fmcp-clickhouse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ClickHouse","download_url":"https://codeload.github.com/ClickHouse/mcp-clickhouse/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242900029,"owners_count":20203704,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-10T18:01:25.207Z","updated_at":"2025-03-10T18:02:23.574Z","avatar_url":"https://github.com/ClickHouse.png","language":"Python","funding_links":[],"categories":["🏢 Enterprise-Supported Implementations","Databases","Database \u0026 Messaging MCP Servers","ツール","📚 Projects (1974 total)","Production-Ready Servers","پیاده‌سازی‌های سرور","🤖 AI/ML","官方 MCP 服务器列表","Official Servers","MCP 服务器精选列表","Legend","MCP Servers","Servers","Ops","Table of Contents","カテゴリ","🗄️ Databases","Uncategorized","🗂️ Extensions by Category","Data \u0026 Analytics"],"sub_categories":["Databases \u0026 Storage","Analytics \u0026 Warehouses","MCPサーバー \u0026 ツール","MCP Servers","🗄️ \u003ca name=\"databases\"\u003e\u003c/a\u003eپایگاه‌های داده","🗄️ 数据库交互","🗄️ \u003ca name=\"databases\"\u003e\u003c/a\u003eDatabases","🗄️ Databases","Data \u0026 Databases","💾 Databases","ETL and Data Processing","Databases","🗄️ \u003ca name=\"database--sql\"\u003e\u003c/a\u003eデータベース・SQL","Uncategorized"],"readme":"# ClickHouse MCP Server\n[![PyPI - Version](https://img.shields.io/pypi/v/mcp-clickhouse)](https://pypi.org/project/mcp-clickhouse)\n\nAn MCP server for ClickHouse.\n\n\u003ca href=\"https://glama.ai/mcp/servers/yvjy4csvo1\"\u003e\u003cimg width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/yvjy4csvo1/badge\" alt=\"mcp-clickhouse MCP server\" /\u003e\u003c/a\u003e\n\n## Features\n\n### Tools\n\n* `run_select_query`\n  - Execute SQL queries on your ClickHouse cluster.\n  - Input: `sql` (string): The SQL query to execute.\n  - All ClickHouse queries are run with `readonly = 1` to ensure they are safe.\n\n* `list_databases`\n  - List all databases on your ClickHouse cluster.\n\n* `list_tables`\n  - List all tables in a database.\n  - Input: `database` (string): The name of the database.\n\n## Configuration\n\n1. Open the Claude Desktop configuration file located at:\n   - On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - On Windows: `%APPDATA%/Claude/claude_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.13\",\n        \"mcp-clickhouse\"\n      ],\n      \"env\": {\n        \"CLICKHOUSE_HOST\": \"\u003cclickhouse-host\u003e\",\n        \"CLICKHOUSE_PORT\": \"\u003cclickhouse-port\u003e\",\n        \"CLICKHOUSE_USER\": \"\u003cclickhouse-user\u003e\",\n        \"CLICKHOUSE_PASSWORD\": \"\u003cclickhouse-password\u003e\",\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://sql.clickhouse.com/), 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.13\",\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\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## 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```\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://docs.astral.sh/uv/). Then do `source .venv/bin/activate`.\n\n4. For easy testing, you can run `mcp dev mcp_clickhouse/mcp_server.py` to start the MCP server.\n\n### Environment Variables\n\nThe following environment variables are used to configure the ClickHouse connection:\n\n#### Required Variables\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#### Optional Variables\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_SECURE`: Enable/disable HTTPS connection\n  - Default: `\"true\"`\n  - Set to `\"false\"` for non-secure connections\n* `CLICKHOUSE_VERIFY`: Enable/disable SSL certificate verification\n  - Default: `\"true\"`\n  - Set to `\"false\"` to disable certificate verification (not recommended for production)\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/receive 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\n#### Example Configurations\n\nFor local development with Docker:\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```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```env\nCLICKHOUSE_HOST=sql-clickhouse.clickhouse.com\nCLICKHOUSE_USER=demo\nCLICKHOUSE_PASSWORD=\n# Uses secure defaults (HTTPS on port 8443)\n```\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.13\",\n        \"mcp-clickhouse\"\n      ],\n      \"env\": {\n        \"CLICKHOUSE_HOST\": \"\u003cclickhouse-host\u003e\",\n        \"CLICKHOUSE_USER\": \"\u003cclickhouse-user\u003e\",\n        \"CLICKHOUSE_PASSWORD\": \"\u003cclickhouse-password\u003e\",\n        \"CLICKHOUSE_DATABASE\": \"\u003coptional-database\u003e\"\n      }\n    }\n  }\n}\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FClickHouse%2Fmcp-clickhouse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FClickHouse%2Fmcp-clickhouse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FClickHouse%2Fmcp-clickhouse/lists"}