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

](https://pypi.org/project/chmcp) ![License](https://opensource.org/licenses/Apache-2.0) ![Code style: black](https://github.com/psf/black) ![Ruff](https://github.com/astral-sh/ruff)

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

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

🚀 快速开始

从我们的分步教程开始：

👉 完成安装教程 -将Claude转变为强大的ClickHouse数据代理

对于有经验的用户，请跳到快速配置下面的部分。

🎯 选择您的用例

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

📊 仅限数据库操作

适用于： ClickHouse数据库的数据分析、查询和探索

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

☁️ 仅限云管理

适用于： 以编程方式管理ClickHouse云基础架构

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

🔄 两者结合

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

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

🌟 为什么选择此服务器？

此存储库比原始ClickHouse MCP服务器:

功能	原始服务器（v0.1.10）	此服务器
数据库操作	3个基本工具	3个具有安全功能的增强工具
查询安全	❌ `run_select_query` 允许任何SQL操作	✅ 正确的查询过滤和只读模式
云管理	❌ 无	✅ 50多种综合工具（API覆盖率100%）
安全控制	❌ 无法防止破坏性操作	✅ 数据库和云操作的高级只读模式
代码质量	基础	生产准备就绪，结构合理
配置	有限的选项	针对任何用例的灵活设置
错误处理	基本	强大，有详细的错误消息
SSL支持	有限	完整SSL配置选项

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

✨ 能力概述

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

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

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

☁️ 云管理（50+工具）

完成ClickHouse Cloud API集成：

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

🔒 安全功能

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

📊 数据库安全

自动只读模式：所有数据库查询都使用 readonly = 1 默认情况下
查询筛选：只允许使用SELECT、SHOW、DESCRIBE和EXPLAIN查询
手动覆盖：设置 CLICKHOUSE_READONLY=false 在需要时启用写入操作

☁️ 云管理安全

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

🛡️ 安全最佳实践

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

⚡ 快速配置

Claude桌面设置

打开您的Claude Desktop配置文件：

- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%/Claude/claude_desktop_config.json

根据您的用例选择配置：

📊 Database Operations Only (Click to expand)

适用于您自己的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"
      }
    }
  }
}

☁️ Cloud Management Only (Click to expand)

{
  "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" 完全访问。

🔄 Both Database + Cloud Management (Click to expand)

{
  "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" 仅用于监控模式。

重要提示： 替换 /path/to/uv 与你的绝对路径 uv 可执行文件（用 which uv 在macOS/Linux上）

重新启动克劳德桌面 应用更改

📦 安装

选项1：使用紫外线（推荐）

# Install via uv (used by Claude Desktop)
uv add chmcp

选项2：手动安装

# Clone the repository
git clone https://github.com/oualib/chmcp.git
cd chmcp

# Install core dependencies
pip install .

# Install with development dependencies
pip install ".[dev]"

# Install with test dependencies
pip install ".[test]"

# Install with documentation dependencies
pip install ".[docs]"

# Install with all optional dependencies
pip install ".[dev,test,docs]"

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

⚙️ 配置指南

📊 数据库配置

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

必需变量

CLICKHOUSE_HOST=your-clickhouse-host.com   # ClickHouse server hostname
CLICKHOUSE_USER=your-username              # Username for authentication
CLICKHOUSE_PASSWORD=your-password          # Password for authentication

安全和安保变量

CLICKHOUSE_READONLY=true                   # Enable read-only mode (recommended)
                                           # true: Only SELECT/SHOW/DESCRIBE queries allowed
                                           # false: All SQL operations permitted

可选变量（默认值）

CLICKHOUSE_PORT=8443                        # 8443 for HTTPS, 8123 for HTTP
CLICKHOUSE_SECURE=true                      # Enable HTTPS connection
CLICKHOUSE_VERIFY=true                      # Verify SSL certificates
CLICKHOUSE_CONNECT_TIMEOUT=30               # Connection timeout in seconds
CLICKHOUSE_SEND_RECEIVE_TIMEOUT=300         # Query timeout in seconds
CLICKHOUSE_DATABASE=default                 # Default database to use

\[！小心\] 安全最佳实践： 总是使用 CLICKHOUSE_READONLY=true 在生产环境中。创建一个具有最低MCP连接权限的专用数据库用户。避免使用管理帐户。

☁️ 云API配置

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

必需变量

CLICKHOUSE_CLOUD_KEY_ID=your-cloud-key-id          # From ClickHouse Cloud Console
CLICKHOUSE_CLOUD_KEY_SECRET=your-cloud-key-secret  # From ClickHouse Cloud Console

安全和安保变量

CLICKHOUSE_CLOUD_READONLY=false            # Cloud operation mode (default: false)
                                           # true: Only read operations (list, get, metrics)
                                           # false: All cloud operations permitted (create, update, delete)

可选变量（默认值）

CLICKHOUSE_CLOUD_API_URL=https://api.clickhouse.cloud   # API endpoint
CLICKHOUSE_CLOUD_TIMEOUT=30                             # Request timeout
CLICKHOUSE_CLOUD_SSL_VERIFY=true                        # SSL verification

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

🔑 获取ClickHouse Cloud API密钥

登录 ClickHouse云控制台
导航至设置 → API密钥
点击 创建API密钥
选择适当的权限：

- 管理员：完全访问所有资源 - 开发者：服务和资源管理 - 查询端点：仅限于查询操作

复制 密钥ID 和 关键秘密 到您的配置

🔒 安全配置示例

Production Safe Mode (Recommended)

# Database - read-only queries only
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=readonly_user
CLICKHOUSE_PASSWORD=secure-password
CLICKHOUSE_SECURE=true
CLICKHOUSE_READONLY=true

# Cloud - monitoring and inspection only (explicitly set to true)
CLICKHOUSE_CLOUD_KEY_ID=your-cloud-key-id
CLICKHOUSE_CLOUD_KEY_SECRET=your-cloud-key-secret
CLICKHOUSE_CLOUD_READONLY=true

Development Mode (Full Access)

# Database - all operations allowed
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_SECURE=false
CLICKHOUSE_READONLY=false

# Cloud - full infrastructure management
CLICKHOUSE_CLOUD_KEY_ID=dev-key-id
CLICKHOUSE_CLOUD_KEY_SECRET=dev-key-secret
CLICKHOUSE_CLOUD_READONLY=false

Analysis Only Mode

# Database - read-only for data analysis
CLICKHOUSE_HOST=analytics.company.com
CLICKHOUSE_USER=analyst
CLICKHOUSE_PASSWORD=analyst-password
CLICKHOUSE_SECURE=true
CLICKHOUSE_READONLY=true

# Cloud - monitoring only, no infrastructure changes
CLICKHOUSE_CLOUD_KEY_ID=monitoring-key-id
CLICKHOUSE_CLOUD_KEY_SECRET=monitoring-key-secret
CLICKHOUSE_CLOUD_READONLY=true

示例配置

Local Development with Docker

# Database only - full access for development
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_SECURE=false
CLICKHOUSE_PORT=8123
CLICKHOUSE_READONLY=false

ClickHouse Cloud (Safe Mode)

# Database connection - read-only
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-database-password
CLICKHOUSE_SECURE=true
CLICKHOUSE_READONLY=true

# Cloud management - monitoring only (explicitly set to true)
CLICKHOUSE_CLOUD_KEY_ID=your-cloud-key-id
CLICKHOUSE_CLOUD_KEY_SECRET=your-cloud-key-secret
CLICKHOUSE_CLOUD_READONLY=true

SSL Issues Troubleshooting

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

# Disable SSL verification for database
CLICKHOUSE_VERIFY=false
CLICKHOUSE_SECURE=false  # Use HTTP instead of HTTPS
CLICKHOUSE_PORT=8123     # HTTP port instead of 8443

# Disable SSL verification for cloud API
CLICKHOUSE_CLOUD_SSL_VERIFY=false

🛠️ 可用工具

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

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

list_databases() -列出所有可用数据库
list_tables(database, like?, not_like?) -列出包含详细元数据（包括架构、行数和列信息）的表
run_query(query) -使用安全控制执行查询：

- 只读模式 (CLICKHOUSE_READONLY=true)：仅选择、显示、描述、解释查询 - 完全访问模式 (CLICKHOUSE_READONLY=false)：所有SQL操作，包括INSERT、UPDATE、DELETE、CREATE、DROP

\[！注意\] 查询安全： 当 CLICKHOUSE_READONLY=true，所有查询都会自动运行 readonly = 1 设置并过滤以防止数据修改操作。

☁️ 云管理工具（50多种工具）

当提供API凭据时，这些工具可与ClickHouse Cloud一起使用。工具可用性取决于 CLICKHOUSE_CLOUD_READONLY 设置：

🔍 只读操作（在以下情况下可用 `CLICKHOUSE_CLOUD_READONLY=true`)

组织监控（3个工具）

cloud_list_organizations() -列出可用组织
cloud_get_organization(organization_id) -获取组织详细信息
cloud_get_organization_metrics(organization_id, filtered_metrics?) -获取Prometheus指标

服务监控（3个工具）

cloud_list_services(organization_id) -列出组织中的所有服务
cloud_get_service(organization_id, service_id) -获取详细的服务信息
cloud_get_service_metrics(organization_id, service_id, filtered_metrics?) -获取服务性能指标

资源检查（8个工具）

cloud_list_api_keys(organization_id) -列出所有API密钥（仅限元数据）
cloud_get_api_key(organization_id, key_id) -获取API密钥详细信息
cloud_list_members(organization_id) -列出组织成员
cloud_get_member(organization_id, user_id) -获取会员详细信息
cloud_list_invitations(organization_id) -列出待处理的邀请
cloud_get_invitation(organization_id, invitation_id) -获取邀请详细信息
cloud_list_backups(organization_id, service_id) -列出服务备份
cloud_get_backup(organization_id, service_id, backup_id) -获取备份详细信息

配置检查（5个工具）

cloud_get_backup_configuration(organization_id, service_id) -获取备份配置
cloud_get_private_endpoint_config(organization_id, service_id) -获取私有端点配置
cloud_list_clickpipes(organization_id, service_id) -列表单击管道
cloud_get_clickpipe(organization_id, service_id, clickpipe_id) -获取ClickPipe详细信息
cloud_get_available_regions() -获取支持的地区

分析和监控（3个工具）

cloud_list_activities(organization_id, from_date?, to_date?) -获取审核日志
cloud_get_activity(organization_id, activity_id) -获取活动详细信息
cloud_get_usage_cost(organization_id, from_date, to_date) -获取使用情况分析

⚠️ 写入操作（仅在以下情况下可用 `CLICKHOUSE_CLOUD_READONLY=false`)

组织管理（2个工具）

cloud_update_organization(organization_id, name?, private_endpoints?) -更新组织设置
cloud_get_organization_private_endpoint_info(organization_id, cloud_provider, region) -获取私有端点信息

服务管理（9个工具）

cloud_create_service(organization_id, name, provider, region, ...) -创建新服务
cloud_update_service(organization_id, service_id, ...) -更新服务设置
cloud_update_service_state(organization_id, service_id, command) -启动/停止服务
cloud_update_service_scaling(organization_id, service_id, ...) -配置扩展（传统）
cloud_update_service_replica_scaling(organization_id, service_id, ...) -配置副本扩展
cloud_update_service_password(organization_id, service_id, ...) -更新服务密码
cloud_create_service_private_endpoint(organization_id, service_id, id, description) -创建私有端点
cloud_delete_service(organization_id, service_id) -删除服务

API密钥管理（3个工具）

cloud_create_api_key(organization_id, name, roles, ...) -创建新的API密钥
cloud_update_api_key(organization_id, key_id, ...) -更新API密钥属性
cloud_delete_api_key(organization_id, key_id) -删除API密钥

用户管理（3个工具）

cloud_update_member_role(organization_id, user_id, role) -更新成员角色
cloud_remove_member(organization_id, user_id) -删除成员
cloud_create_invitation(organization_id, email, role) -发送邀请
cloud_delete_invitation(organization_id, invitation_id) -取消邀请

基础设施管理（12个工具）

cloud_update_backup_configuration(organization_id, service_id, ...) -更新备份设置
cloud_create_clickpipe(organization_id, service_id, name, description, source, destination, field_mappings?) -创建ClickPipe
cloud_update_clickpipe(organization_id, service_id, clickpipe_id, ...) -更新点击管道
cloud_update_clickpipe_scaling(organization_id, service_id, clickpipe_id, replicas?) -缩放ClickPipe
cloud_update_clickpipe_state(organization_id, service_id, clickpipe_id, command) -控制单击管道状态
cloud_delete_clickpipe(organization_id, service_id, clickpipe_id) -删除ClickPipe
cloud_list_reverse_private_endpoints(organization_id, service_id) -列出反向私有端点
cloud_create_reverse_private_endpoint(organization_id, service_id, ...) -创建反向私有端点
cloud_get_reverse_private_endpoint(organization_id, service_id, reverse_private_endpoint_id) -获取详细信息
cloud_delete_reverse_private_endpoint(organization_id, service_id, reverse_private_endpoint_id) -删除端点
cloud_create_query_endpoint_config(organization_id, service_id, roles, open_api_keys, allowed_origins) -创建查询配置
cloud_delete_query_endpoint_config(organization_id, service_id) -删除查询配置

\[！小心\] 生产警告： 写操作可以创建计费资源、修改正在运行的服务或删除基础架构。总是使用 CLICKHOUSE_CLOUD_READONLY=true 除非特别需要改变基础设施。

💡 使用示例

📊 数据库操作示例

安全分析模式

# With CLICKHOUSE_READONLY=true (recommended for production)
# Only analytical queries are allowed

# Explore database structure
databases = list_databases()
print(f"Available databases: {[db['name'] for db in databases]}")

# Get detailed table information
tables = list_tables("my_database")
for table in tables:
    print(f"Table: {table['name']}, Rows: {table['total_rows']}")

# Execute analytical queries safely
result = run_query("""
    SELECT 
        date_trunc('day', timestamp) as day,
        count(*) as events,
        avg(value) as avg_value
    FROM my_table 
    WHERE timestamp >= '2024-01-01'
    GROUP BY day
    ORDER BY day
""")

# These queries would be blocked in readonly mode:
# run_query("DROP TABLE my_table")  # ❌ Blocked
# run_query("INSERT INTO my_table VALUES (1)")  # ❌ Blocked
# run_query("UPDATE my_table SET value = 0")  # ❌ Blocked

完全访问模式

# With CLICKHOUSE_READONLY=false (development only)
# All SQL operations are allowed

# Data modification operations
run_query("""
    CREATE TABLE test_table (
        id UInt32,
        name String,
        created_at DateTime
    ) ENGINE = MergeTree()
    ORDER BY id
""")

run_query("INSERT INTO test_table VALUES (1, 'test', now())")
run_query("UPDATE test_table SET name = 'updated' WHERE id = 1")

☁️ 云管理示例

监控模式（安全）

# With CLICKHOUSE_CLOUD_READONLY=true (recommended for production)
# Only monitoring and inspection operations

# Monitor organization resources
orgs = cloud_list_organizations()
for org in orgs:
    services = cloud_list_services(org['id'])
    print(f"Organization: {org['name']}, Services: {len(services)}")
    
    # Get service metrics
    for service in services:
        metrics = cloud_get_service_metrics(org['id'], service['id'])
        print(f"Service {service['name']} metrics: {metrics}")

# Monitor costs and usage
usage = cloud_get_usage_cost(
    organization_id="org-123",
    from_date="2024-01-01",
    to_date="2024-01-31"
)
print(f"Monthly cost: ${usage['total_cost']}")

# Audit recent activities
activities = cloud_list_activities(
    organization_id="org-123",
    from_date="2024-01-01T00:00:00Z"
)
print(f"Recent activities: {len(activities)} events")

# These operations would be blocked in readonly mode:
# cloud_create_service(...)  # ❌ Blocked
# cloud_delete_service(...)  # ❌ Blocked  
# cloud_update_service_state(...)  # ❌ Blocked

基础设施管理（完全访问）

# With CLICKHOUSE_CLOUD_READONLY=false (use with caution)
# All infrastructure operations allowed

# Create a production service with full configuration
service = cloud_create_service(
    organization_id="org-123",
    name="analytics-prod",
    provider="aws",
    region="us-east-1",
    tier="production",
    min_replica_memory_gb=32,
    max_replica_memory_gb=256,
    num_replicas=3,
    idle_scaling=True,
    idle_timeout_minutes=10,
    ip_access_list=[
        {"source": "10.0.0.0/8", "description": "Internal network"},
        {"source": "203.0.113.0/24", "description": "Office network"}
    ]
)

# Start the service and monitor status
cloud_update_service_state(
    organization_id="org-123",
    service_id=service['id'],
    command="start"
)

# Set up automated backups
cloud_update_backup_configuration(
    organization_id="org-123",
    service_id=service['id'],
    backup_period_in_hours=24,
    backup_retention_period_in_hours=168,  # 7 days
    backup_start_time="02:00"
)

🔄 安全组合工作流示例

# Production-safe configuration for monitoring and analysis
# CLICKHOUSE_READONLY=true + CLICKHOUSE_CLOUD_READONLY=true

# 1. Monitor existing cloud infrastructure
orgs = cloud_list_organizations()
org_id = orgs[0]['id']

services = cloud_list_services(org_id)
active_services = [s for s in services if s['state'] == 'running']
print(f"Active services: {len(active_services)}")

# 2. Analyze data from running services
for service in active_services:
    # Check service health
    metrics = cloud_get_service_metrics(org_id, service['id'])
    
    # Analyze data (read-only queries)
    if service['endpoints']:
        # Connect to database (would use service endpoint)
        result = run_query("""
            SELECT 
                database,
                table,
                sum(rows) as total_rows,
                sum(bytes_on_disk) as disk_usage
            FROM system.parts
            WHERE active = 1
            GROUP BY database, table
            ORDER BY total_rows DESC
            LIMIT 10
        """)
        
        print(f"Top tables in {service['name']}: {result}")

# 3. Generate usage report
usage = cloud_get_usage_cost(
    organization_id=org_id,
    from_date="2024-01-01",
    to_date="2024-01-31"
)

activities = cloud_list_activities(org_id)
recent_changes = [a for a in activities if 'create' in a.get('action', '').lower()]

print(f"""
Monthly Report:
- Total Cost: ${usage.get('total_cost', 'N/A')}
- Active Services: {len(active_services)}
- Recent Infrastructure Changes: {len(recent_changes)}
""")

🔧 发展

地方发展设置

启动ClickHouse进行测试:

   cd test-services
   docker compose up -d

创建环境文件:

   cat > .env << EOF
   # Database configuration (development mode)
   CLICKHOUSE_HOST=localhost
   CLICKHOUSE_PORT=8123
   CLICKHOUSE_USER=default
   CLICKHOUSE_PASSWORD=clickhouse
   CLICKHOUSE_SECURE=false
   CLICKHOUSE_READONLY=false

   # Cloud configuration (optional, safe mode)
   CLICKHOUSE_CLOUD_KEY_ID=your-key-id
   CLICKHOUSE_CLOUD_KEY_SECRET=your-key-secret
   CLICKHOUSE_CLOUD_READONLY=true
   EOF

安装并运行:

   uv sync                               # Install dependencies
   source .venv/bin/activate            # Activate virtual environment
   mcp dev chmcp/mcp_server.py          # Start for testing
   # OR
   python -m chmcp.main                 # Start normally

测试安全功能

# Test read-only database mode
CLICKHOUSE_READONLY=true python -m chmcp.main

# Test cloud monitoring mode  
CLICKHOUSE_CLOUD_READONLY=true python -m chmcp.main

# Test full access mode (development only)
CLICKHOUSE_READONLY=false CLICKHOUSE_CLOUD_READONLY=false python -m chmcp.main

项目结构

chmcp/
├── __init__.py                 # Package initialization
├── main.py                     # Entry point
├── mcp_env.py                  # Database environment configuration
├── mcp_server.py              # Main server + database tools (3 tools)
├── cloud_config.py            # Cloud API configuration
├── cloud_client.py            # HTTP client for Cloud API
└── cloud_tools.py             # Cloud MCP tools (50+ tools)

运行测试

uv sync --all-extras --dev              # Install dev dependencies
uv run ruff check .                     # Run linting
docker compose up -d                    # Start test ClickHouse
uv run pytest tests                     # Run tests

🐛 故障排除

📊 数据库连接问题

问题： 无法连接到ClickHouse数据库

✅ 验证 CLICKHOUSE_HOST, CLICKHOUSE_USER，以及 CLICKHOUSE_PASSWORD
✅ 测试网络连接： telnet your-host 8443
✅ 检查防火墙设置是否允许在指定端口上连接
✅ 对于SSL问题，请尝试设置 CLICKHOUSE_VERIFY=false
✅ 确保数据库用户具有适当的SELECT权限

问题： SSL证书验证失败

# Temporarily disable SSL verification
CLICKHOUSE_VERIFY=false
CLICKHOUSE_SECURE=false  # Use HTTP instead of HTTPS
CLICKHOUSE_PORT=8123     # HTTP port instead of 8443

问题： 查询被阻止

✅ 检查是否 CLICKHOUSE_READONLY=true 正在阻止写入操作
✅ 为了开发，暂时设置 CLICKHOUSE_READONLY=false
✅ 检查禁止操作的查询（INSERT、UPDATE、DELETE、CREATE、DROP）
✅ 请改用SHOW、DESCRIBE、EXPLAIN或SELECT查询

☁️ 云API问题

问题： 云工具不工作

✅ 验证 CLICKHOUSE_CLOUD_KEY_ID 和 CLICKHOUSE_CLOUD_KEY_SECRET 是正确的
✅ 在ClickHouse云控制台中检查API密钥权限
✅ 确保API密钥处于活动状态且未过期
✅ 对于SSL问题，请尝试设置 CLICKHOUSE_CLOUD_SSL_VERIFY=false

问题： “不允许操作”错误

✅ 检查是否 CLICKHOUSE_CLOUD_READONLY=true 正在阻止写入操作
✅ 对于基础设施管理，设置 CLICKHOUSE_CLOUD_READONLY=false
✅ 验证API密钥是否有足够的权限执行请求的操作
✅ 审查操作类型：监控操作以只读模式工作，管理操作需要写访问权限

问题： “找不到组织”错误

✅ 首先列出组织： cloud_list_organizations()
✅ 验证您的API密钥是否可以访问组织
✅ 检查您是否使用了正确的组织ID格式

🔧 一般问题

问题： Claude中缺少的工具

✅ 数据库工具需要数据库配置(CLICKHOUSE_HOST等等）
✅ 云工具需要API配置(CLICKHOUSE_CLOUD_KEY_ID等等）
✅ 检查Claude Desktop配置文件语法
✅ 配置更改后重新启动Claude Desktop
✅ 验证 uv 路径在配置中是绝对的

问题： 安全功能未按预期工作

✅ 确认环境变量设置正确： echo $CLICKHOUSE_READONLY
✅ 检查布尔值是否为字符串： "true" 不 true JSON配置中
✅ 更改只读设置后重新启动MCP服务器
✅ 首先用简单的操作进行测试，以验证行为

问题： 导入错误或缺少依赖项

# Reinstall with latest dependencies
uv sync --force
# Core dependencies with force reinstall
pip install . --force-reinstall

# With development dependencies
pip install ".[dev]" --force-reinstall

# With all optional dependencies
pip install ".[dev,test,docs]" --force-reinstall

# Editable install with force reinstall
pip install -e ".[dev]" --force-reinstall

🔒 安全配置故障排除

问题： 希望暂时启用写入操作

# For database operations
export CLICKHOUSE_READONLY=false
# For cloud operations  
export CLICKHOUSE_CLOUD_READONLY=false
# Restart MCP server

问题： 在生产环境中意外启用写入模式

# Immediately disable write operations
export CLICKHOUSE_READONLY=true
export CLICKHOUSE_CLOUD_READONLY=true
# Restart MCP server
# Review audit logs: cloud_list_activities()

问题： 不清楚哪些操作被阻止

✅ 数据库只读模式块： 插入、更新、删除、创建、删除、更改、截断
✅ 数据库只读模式允许： 选择、显示、描述、解释、使用（只读）
✅ 云只读模式块： 创建\_*，更新\_*、delete\_\*、启动/停止服务
✅ 云只读模式允许： 列表\_*，得到\_*、指标、监控、分析

📄 许可证

此项目根据Apache许可证2.0获得许可。看许可证文件以获取详细信息。

由...开发巴德尔·瓦利

MCP ClickHouse

快速接入

详细介绍

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

🚀 快速开始

📚 目录

🎯 选择您的用例

📊 仅限数据库操作

☁️ 仅限云管理

🔄 两者结合

🌟 为什么选择此服务器？

✨ 能力概述

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

☁️ 云管理（50+工具）

🔒 安全功能

📊 数据库安全

☁️ 云管理安全

🛡️ 安全最佳实践

⚡ 快速配置

Claude桌面设置

适用于您自己的ClickHouse服务器

ClickHouse云数据库

免费测试（SQL游乐场）

📦 安装

选项1：使用紫外线（推荐）

选项2：手动安装

⚙️ 配置指南

📊 数据库配置

必需变量

安全和安保变量

可选变量（默认值）

☁️ 云API配置

必需变量

安全和安保变量

可选变量（默认值）

🔑 获取ClickHouse Cloud API密钥

🔒 安全配置示例

示例配置

🛠️ 可用工具

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

☁️ 云管理工具（50多种工具）

🔍 只读操作（在以下情况下可用 CLICKHOUSE_CLOUD_READONLY=true)

⚠️ 写入操作（仅在以下情况下可用 CLICKHOUSE_CLOUD_READONLY=false)

💡 使用示例

📊 数据库操作示例

安全分析模式

完全访问模式

☁️ 云管理示例

监控模式（安全）

基础设施管理（完全访问）

🔄 安全组合工作流示例

🔧 发展

地方发展设置

测试安全功能

项目结构

运行测试

🐛 故障排除

📊 数据库连接问题

☁️ 云API问题

🔧 一般问题

🔒 安全配置故障排除

📄 许可证

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

🔍 只读操作（在以下情况下可用 `CLICKHOUSE_CLOUD_READONLY=true`)

⚠️ 写入操作（仅在以下情况下可用 `CLICKHOUSE_CLOUD_READONLY=false`)