🚀 ClickHouse MCP 服务器

ClickHouse MCP 服务器是一个基于 Model Context Protocol (MCP) 的服务，它能与 ClickHouse 数据库建立连接。借助该服务器，大型语言模型（如 Claude）可以通过自然语言查询的方式，对数据库中的数据进行探索和分析，极大地提升了数据交互的便捷性。

🚀 快速开始

ClickHouse MCP 服务器的使用十分便捷，你可以按照以下步骤进行操作：

1. 克隆此仓库。
2. 安装依赖项：

npm install

3. 在 .env 文件中配置环境变量（参考 .env.example）。请确保使用只读数据库用户以限制 DDL 和 DML 执行
4. 构建项目：

npm run build

5. 本地运行服务器：

npm start

6. 与 Claude Desktop 集成：
   • 创建或更新你的 Claude Desktop 配置文件：在 macOS 上，配置文件路径为 ~/Library/Application Support/Claude/claude_desktop_config.json。
   • 添加服务器配置：

{
  "mcpServers": {
    "clickhouse-analytics": {
      "command": "node",
      "args": [
        "/absolute/path/to/clickhouse-mcp-server/dist/index.js"
      ],
      "env": {
        "CLICKHOUSE_URL": "your_clickhouse_url",
        "CLICKHOUSE_USERNAME": "your_username",
        "CLICKHOUSE_PASSWORD": "your_password",
        "CLICKHOUSE_DATABASE": "your_database"
      }
    }
  }
}

- 重新启动 Claude Desktop

✨ 主要特性

• 数据库连接：能够稳定连接到 ClickHouse 数据库。
• 资源暴露：将表架构作为资源进行暴露，方便查询。
• 自然语言查询：支持从自然语言指令运行 SQL 查询。
• 只读查询：仅允许执行只读 SQL 查询，保障数据安全。
• 兼容性：可与 macOS 上的 Claude Desktop 配合使用。

📺 演示

你可以通过以下链接查看演示：演示链接

💻 使用示例

可用资源

• db://info - 数据库信息，包括表和架构
• table://{tableName}/schema - 特定表的架构
• table://{tableName}/sample - 特定表的样本数据（5 行）

可用工具

• execute-sql - 对数据库执行只读 SQL 查询
• natural-language-query - 以自然语言形式提问关于数据的问题

⚠️ 安全注意事项

• 此服务器仅允许执行只读 SQL 查询，从根本上限制了数据的修改风险。
• 敏感凭证应安全地存储在环境变量中，避免信息泄露。
• 服务器执行基本验证以防止 DDL 或 DML 语句的执行。
• 请始终在执行查询请求前进行审查，确保查询的安全性和合理性。

📄 许可证

本项目采用 MIT 许可证。