Clickhouse MCP Server

🚀 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 許可證。