STARWARCLOUD STARWAR.AI
返回市场
化学MCP服务器

化学MCP服务器

作者：oualib6 星标更新：2025-06-30
安装使用来源：spider==github.com

项目介绍

MCP ClickHouse: 数据库操作 + 云管理

PyPI - 版本 Python 3.12+ License Code style: black Ruff

一个全面的模型上下文协议（MCP）服务器，提供两种独立的能力：

  1. 数据库操作 - 连接到并查询任何ClickHouse数据库（本地、云端或自托管）
  2. 云管理 - 通过API完成完整的ClickHouse云基础设施管理

🚀 快速开始

从我们的逐步教程开始：

👉 完整设置教程 - 将Claude转变为强大的ClickHouse数据代理

对于有经验的用户，可以直接跳到快速配置部分。

📚 目录

🎯 选择您的用例

此MCP服务器支持两个独立的用例。您可以使用其中一个或两者：

📊 仅数据库操作

适用场景： 数据分析、查询和探索ClickHouse数据库

  • 连接到任何ClickHouse实例（本地、自托管或ClickHouse云）
  • 安全执行只读查询
  • 探索数据库模式和元数据
  • 设置： 数据库连接凭证

☁️ 仅云管理

适用场景： 编程方式管理ClickHouse云基础设施

  • 创建、配置和管理云服务
  • 处理API密钥、成员和组织
  • 监控使用情况、成本和性能
  • 设置： ClickHouse云API密钥

🔄 结合两者

适用场景： 从基础设施到数据的完整ClickHouse工作流程

  • 管理云服务并查询其中的数据库
  • 端到端的数据管道管理
  • 设置： 数据库凭证和云API密钥

🌟 为什么选择这个服务器？

此仓库显著改进了原始ClickHouse MCP服务器：

功能原始服务器 (v0.1.10)此服务器
数据库操作3个基本工具3个增强工具，带有安全特性
查询安全性❌ run_select_query允许任何SQL操作✅ 合适的查询过滤和只读模式
云管理❌ 无✅ 超过50种全面工具（100% API覆盖）
安全控制❌ 没有防止破坏性操作的保护✅ 先进的数据库和云操作只读模式
代码质量基础生产就绪，具有合适的结构
配置有限选项适用于任何用例的灵活设置
错误处理基础强大的详细错误消息
SSL支持有限完整的SSL配置选项

[!WARNING] 安全通知： 原始ClickHouse MCP服务器（v0.1.10）存在严重安全漏洞，run_select_query可以执行包括DROP、DELETE、INSERT等在内的任何SQL操作，尽管其名称表明它只运行SELECT查询。此服务器实现了适当的查询过滤和安全控制。

✨ 功能概述

📊 数据库操作（3个工具）

连接到并查询任何ClickHouse数据库：

  • 列出数据库和表，带有详细的元数据
  • 执行SELECT查询，带有安全保证（只读模式）
  • 探索模式，包括列类型、行数和表结构
  • 支持： 本地ClickHouse、自托管实例、ClickHouse云数据库以及免费的SQL游乐场

☁️ 云管理（超过50个工具）

完全集成ClickHouse云API：

  • 组织（5个工具）：管理设置、指标、私有端点
  • 服务（12个工具）：创建、扩展、启动/停止、配置、删除云服务
  • API密钥（5个工具）：完整的CRUD操作以实现编程访问
  • 成员与邀请（8个工具）：用户管理和访问控制
  • 备份（4个工具）：配置和管理自动备份
  • ClickPipes（7个工具）：数据摄取管道管理
  • 监控（3个工具）：使用分析、成本和审计日志
  • 网络（6个工具）：私有端点和安全配置

🔒 安全特性

此MCP服务器包括全面的安全控制，以防止意外的数据修改或基础设施更改：

📊 数据库安全

  • 自动只读模式：所有数据库查询默认运行readonly = 1
  • 查询过滤：仅允许SELECT、SHOW、DESCRIBE和EXPLAIN查询
  • 手动覆盖：设置CLICKHOUSE_READONLY=false以在需要时启用写入操作

☁️ 云管理安全

  • 受保护的操作：破坏性的云操作（删除、停止）可以被启用
  • 安全模式：设置CLICKHOUSE_CLOUD_READONLY=false以允许基础设施更改
  • 审计跟踪：所有操作都被记录以确保责任

🛡️ 安全最佳实践

  • 最小权限：创建具有有限权限的专用用户
  • 默认SSL：自动启用安全连接
  • 环境变量：敏感凭据从不硬编码
  • 超时控制：防止失控的查询和操作

⚡ 快速配置

Claude桌面设置

  1. 打开您的Claude桌面配置文件：

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%/Claude/claude_desktop_config.json

  2. 根据您的用例选择配置：

<details> <summary><strong>📊 仅数据库操作</strong>（点击展开）</summary>

对于您自己的ClickHouse服务器

{
  "mcpServers": {
    "chmcp": {
      "command": "/path/to/uv",
      "args": ["run", "--with", "chmcp", "--python", "3.13", "chmcp"],
      "env": {
        "CLICKHOUSE_HOST": "your-server.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "your-username",
        "CLICKHOUSE_PASSWORD": "your-password",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_READONLY": "true"
      }
    }
  }
}

对于ClickHouse云数据库

{
  "mcpServers": {
    "chmcp": {
      "command": "/path/to/uv",
      "args": ["run", "--with", "chmcp", "--python", "3.13", "chmcp"],
      "env": {
        "CLICKHOUSE_HOST": "your-instance.clickhouse.cloud",
        "CLICKHOUSE_USER": "default",
        "CLICKHOUSE_PASSWORD": "your-database-password",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_READONLY": "true"
      }
    }
  }
}

对于免费测试（SQL游乐场）

{
  "mcpServers": {
    "chmcp": {
      "command": "/path/to/uv",
      "args": ["run", "--with", "chmcp", "--python", "3.13", "chmcp"],
      "env": {
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_READONLY": "true"
      }
    }
  }
}
</details> <details> <summary><strong>☁️ 仅云管理</strong>（点击展开）</summary> 
{
  "mcpServers": {
    "chmcp": {
      "command": "/path/to/uv",
      "args": ["run", "--with", "chmcp", "--python", "3.13", "chmcp"],
      "env": {
        "CLICKHOUSE_CLOUD_KEY_ID": "your-cloud-key-id",
        "CLICKHOUSE_CLOUD_KEY_SECRET": "your-cloud-key-secret"
      }
    }
  }
}

注意： CLICKHOUSE_CLOUD_READONLY默认为true（仅监控模式）。添加"CLICKHOUSE_CLOUD_READONLY": "false"以获得完整访问权限。

</details> <details> <summary><strong>🔄 数据库 + 云管理</strong>（点击展开）</summary> 
{
  "mcpServers": {
    "chmcp": {
      "command": "/path/to/uv",
      "args": ["run", "--with", "chmcp", "--python", "3.13", "chmcp"],
      "env": {
        "CLICKHOUSE_HOST": "your-instance.clickhouse.cloud",
        "CLICKHOUSE_USER": "default",
        "CLICKHOUSE_PASSWORD": "your-database-password",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_READONLY": "true",
        "CLICKHOUSE_CLOUD_KEY_ID": "your-cloud-key-id",
        "CLICKHOUSE_CLOUD_KEY_SECRET": "your-cloud-key-secret"
      }
    }
  }
}

注意： 这将启用数据库分析（只读）+ 完整的云管理。添加"CLICKHOUSE_CLOUD_READONLY": "true"以进入仅监控模式。

</details>

  1. 重要提示： 将/path/to/uv替换为您uv可执行文件的绝对路径（在macOS/Linux上使用which uv找到）

  2. 重启Claude桌面以应用更改

📦 安装

选项1：使用uv（推荐）

# 通过uv安装（用于Claude桌面）
uv add chmcp

选项2：手动安装

# 克隆仓库
git clone https://github.com/oualib/chmcp.git
cd chmcp

# 安装核心依赖
pip install .

# 安装开发依赖
pip install ".[dev]"

# 安装测试依赖
pip install ".[test]"

# 安装文档依赖
pip install ".[docs]"

# 安装所有可选依赖
pip install ".[dev,test,docs]"

# 设置环境变量
cp .env.example .env
# 编辑.env以匹配您的配置

⚙️ 配置指南

📊 数据库配置

设置这些环境变量以启用数据库操作：

必需变量

CLICKHOUSE_HOST=your-clickhouse-host.com   # ClickHouse服务器主机名
CLICKHOUSE_USER=your-username              # 认证用户名
CLICKHOUSE_PASSWORD=your-password          # 认证密码

安全与安全变量

CLICKHOUSE_READONLY=true                   # 启用只读模式（推荐）
                                           # true: 只允许SELECT/SHOW/DESCRIBE查询
                                           # false: 允许所有SQL操作

可选变量（默认值）

CLICKHOUSE_PORT=8443                        # 8443用于HTTPS，8123用于HTTP
CLICKHOUSE_SECURE=true                      # 启用HTTPS连接
CLICKHOUSE_VERIFY=true                      # 验证SSL证书
CLICKHOUSE_CONNECT_TIMEOUT=30               # 连接超时（秒）
CLICKHOUSE_SEND_RECEIVE_TIMEOUT=300         # 查询超时（秒）
CLICKHOUSE_DATABASE=default                 # 默认使用的数据库

[!CAUTION] 安全最佳实践： 在生产环境中始终使用CLICKHOUSE_READONLY=true。为MCP连接创建具有最小权限的专用数据库用户。避免使用管理员账户。

☁️ 云API配置

设置这些环境变量以启用云管理：

必需变量

CLICKHOUSE_CLOUD_KEY_ID=your-cloud-key-id          # 来自ClickHouse云控制台
CLICKHOUSE_CLOUD_KEY_SECRET=your-cloud-key-secret  # 来自ClickHouse云控制台

安全与安全变量

CLICKHOUSE_CLOUD_READONLY=false            # 云操作模式（默认：false）
                                           # true: 只允许读操作（列表、获取、指标）
                                           # false: 允许所有云操作（创建、更新、删除）

可选变量（默认值）

CLICKHOUSE_CLOUD_API_URL=https://api.clickhouse.cloud   # API端点
CLICKHOUSE_CLOUD_TIMEOUT=30                             # 请求超时
CLICKHOUSE_CLOUD_SSL_VERIFY=true                        # SSL验证

[!WARNING] 云安全： 默认情况下，CLICKHOUSE_CLOUD_READONLY=false允许所有基础设施操作。在生产中设置为true以防止意外的基础设施更改。当禁用时，Claude可以创建、修改和删除云服务，这可能会产生费用或导致服务中断。

🔑 获取ClickHouse云API密钥

  1. 登录到ClickHouse云控制台
  2. 导航至设置 → API密钥
  3. 点击创建API密钥
  4. 选择适当的权限：
    • 管理员：对所有资源的完全访问
    • 开发者：服务和资源管理
    • 查询端点：仅限查询操作
  5. 复制密钥ID和密钥秘密到您的配置

🔒 安全配置示例

<details> <summary><strong>生产安全模式（推荐）</strong></summary> 
# 数据库 - 只读查询
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=readonly_user
CLICKHOUSE_PASSWORD=secure-password
CLICKHOUSE_SECURE=true
CLICKHOUSE_READONLY=true

# 云 - 仅监控和检查（显式设置为true）
CLICKHOUSE_CLOUD_KEY_ID=your-cloud-key-id
CLICKHOUSE_CLOUD_KEY_SECRET=your-cloud-key-secret
CLICKHOUSE_CLOUD_READONLY=true
</details> <details> <summary><strong>开发模式（完全访问）</strong></summary> 
# 数据库 - 允许所有操作
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_SECURE=false
CLICKHOUSE_READONLY=false

# 云 - 完整基础设施管理
CLICKHOUSE_CLOUD_KEY_ID=dev-key-id
CLICKHOUSE_CLOUD_KEY_SECRET=dev-key-secret
CLICKHOUSE_CLOUD_READONLY=false
</details> <details> <summary><strong>仅分析模式</strong></summary> 
# 数据库 - 仅读取分析
CLICKHOUSE_HOST=analytics.company.com
CLICKHOUSE_USER=analyst
CLICKHOUSE_PASSWORD=analyst-password
CLICKHOUSE_SECURE=true
CLICKHOUSE_READONLY=true

# 云 - 仅监控，无基础设施更改
CLICKHOUSE_CLOUD_KEY_ID=monitoring-key-id
CLICKHOUSE_CLOUD_KEY_SECRET=monitoring-key-secret
CLICKHOUSE_CLOUD_READONLY=true
</details>

示例配置

<details> <summary><strong>本地开发与Docker</strong></summary> 
# 仅数据库 - 开发完全访问
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_SECURE=false
CLICKHOUSE_PORT=8123
CLICKHOUSE_READONLY=false
</details> <details> <summary><strong>ClickHouse云（安全模式）</strong></summary> 
# 数据库连接 - 只读
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-database-password
CLICKHOUSE_SECURE=true
CLICKHOUSE_READONLY=true

# 云管理 - 仅监控（显式设置为true）
CLICKHOUSE_CLOUD_KEY_ID=your-cloud-key-id
CLICKHOUSE_CLOUD_KEY_SECRET=your-cloud-key-secret
CLICKHOUSE_CLOUD_READONLY=true
</details> <details> <summary><strong>SSL问题故障排除</strong></summary>

如果您遇到SSL证书验证问题：

# 禁用数据库的SSL验证
CLICKHOUSE_VERIFY=false
CLICKHOUSE_SECURE=false  # 使用HTTP而不是HTTPS
CLICKHOUSE_PORT=8123     # 使用HTTP端口而不是8443

# 禁用云API的SSL验证
CLICKHOUSE_CLOUD_SSL_VERIFY=false
</details>

🛠️ 可用工具

📊 数据库工具（3个工具）

这些工具在提供数据库配置时可用于任何ClickHouse数据库：

  • list_databases() - 列出所有可用数据库
  • list_tables(database, like?, not_like?) - 列出带有详细元数据的表，包括模式、行数和