Atomic Crm MCP

🚀 Atomic CRM MCP 服務器

Atomic CRM MCP 服務器是一個用於 Atomic CRM 的 MCP（模型上下文協議）服務器。它能讓代理（如 ChatGPT、Claude 等）安全地對 Atomic CRM 實例進行數據讀寫操作。

• 通過 Supabase 實現 OAuth 2.1 認證
• 添加 query 工具，可對 CRM 數據庫執行 SQL 查詢
• 自動實施行級安全（RLS）

✨ 主要特性

支持的 MCP 客戶端

• ChatGPT
• Claude.ai
• Visual Studio Code
• Claude Desktop
• Claude Code
• Cursor
• Goose
• Codex CLI
• Gemini CLI
• Gemini Mobile
• ChatGPT Desktop
• ChatGPT Mobile

📦 安裝指南

MCP 服務器設置

1. 克隆倉庫：

   git clone https://github.com/marmelab/atomic-crm-mcp
   cd your-repo
   

2. 安裝依賴：

   npm install
   

3. 添加配置文件

   cp .env.example .env
   

Supabase 設置

1. 打開 Supabase 儀表盤

   • 訪問 https://supabase.com/dashboard 並選擇你的項目（或創建一個新項目）

2. 啟用 OAuth 2.1 服務器

   • 進入 認證 → OAuth 服務器
   • 點擊 啟用 Supabase OAuth 服務器
   • 將 授權路徑 設置為 /#/oauth/consent
   • 啟用 允許動態 OAuth 應用 選項
   • 保存更改

3. 配置非對稱 JWT 簽名

   • 進入 項目設置 → JWT 密鑰
   • 在 JWT 簽名密鑰 選項卡中，如果你看到 開始使用 JWT 簽名密鑰 的提示，這意味著你當前使用的是舊版 JWT 密鑰，點擊 遷移 JWT 密鑰 按鈕
   • 如果當前密鑰類型為 "Legacy HS256 (共享密鑰)"，點擊 旋轉密鑰 以使用新的 "ECC (P256)" 或類似類型的密鑰

4. 獲取 Supabase URL

   • 進入 項目設置 → 數據 API
   • 找到你的 項目 URL（例如，https://mrubnlemopavyqvjjwmw.supabase.co）
   • 將其添加到 .env 文件中，作為 SUPABASE_URL

5. 獲取數據庫連接字符串

   • 進入 項目設置 → 數據庫
   • 在頂部應用欄中，點擊 連接 按鈕
   • 複製 直接連接 字符串（其中會有 [YOUR-PASSWORD] 佔位符）
   • 將其添加到 .env 文件中，作為 DATABASE_URL
   • 將 [YOUR-PASSWORD] 替換為你的數據庫密碼。如果你不知道密碼，進入 數據庫 → 設置 並重置密碼。

本地 MCP 服務器

如果你使用 ngrok 等服務，可以在本地運行 MCP 服務器。你需要為 MCP 服務器選擇一個可公開訪問的 HTTPS URL，例如 https://atomiccrmmcp.ngrok.dev。在下面的說明中，我們將此 URL 稱為 MCP_URL。

使用自定義 URL 運行服務器：

npm run dev -- --url=MCP_URL

然後，在另一個終端中使用相同的 URL 啟動 ngrok：

ngrok http --url MCP_URL 3000   

現在，MCP 服務器可以通過 ngrok URL 訪問。

託管 MCP 服務器

將 MCP 服務器部署到你選擇的託管提供商。確保在託管提供商的設置中設置 .env 文件中的環境變量。

請注意，主機必須支持 IPV6，因為 Supabase 直接數據庫連接不支持 IPV4。這排除了僅支持 IPV4 的提供商，如 Vercel 或 GitHub actions。

將 MCP 服務器添加到 Chat GPT

注意：Atomic CRM MCP 在 ChatGPT 的網頁版和移動版上都可以使用。你需要一個付費的 Chat GPT 賬戶才能使用自定義連接器。

1. 在 設置 → 應用 → 高級 設置中啟用 開發者模式
2. 然後，在 設置 → 應用 下，點擊創建按鈕
3. 按如下方式填寫字段：
   • 名稱：Atomic CRM
   • MCP 服務器 URL：（你的 MCP 服務器 URL，例如 MCP_URL/mcp）
   • 認證方式：OAuth
   • 勾選 “我理解並希望繼續” 複選框
4. 點擊 “創建”
5. 會打開一個瀏覽器窗口，讓你對 Atomic CRM 進行身份驗證並允許 Claude Code 訪問。
6. 身份驗證完成後，你就可以在 Chat GPT 中開始使用 Atomic CRM 擴展。

如果你使用的是工作區或組織賬戶，需要請求管理員添加並批准自定義連接器，然後才能使用。

將 MCP 服務器添加到 Claude.ai

注意：Atomic CRM MCP 在 Claude 的網頁版和移動版上都可以使用。你需要一個付費的 Claude.ai 賬戶才能使用自定義連接器。

1. 打開 Claude.ai 並打開 設置 → 連接器 頁面
2. 然後點擊 “添加自定義連接器”
3. 按如下方式填寫字段：
   • 名稱：Atomic CRM
   • MCP 服務器 URL：（你的 MCP 服務器 URL，例如 MCP_URL/mcp）
4. 點擊 “添加”
5. 會打開一個瀏覽器窗口，讓你對 Atomic CRM 進行身份驗證並允許 Claude Code 訪問。
6. 身份驗證完成後，你就可以在 Chat GPT 中開始使用 Atomic CRM 擴展。

將 MCP 服務器添加到 Visual Studio Code

1. 打開命令面板（Ctrl+Shift+P 或 Cmd+Shift+P）並運行 “MCP: 添加服務器...” 命令。
2. 在列出 MCP 類型的下拉列表中，選擇 “HTTP”
3. 提示時輸入 MCP 服務器 URL（例如 MCP_URL/mcp）。
4. 提示時將此服務器命名為 atomic-crm。
5. 根據需要選擇 “全局” 或 “本地” 範圍。
6. 會打開一個對話框，讓你對 Atomic CRM 進行身份驗證並允許訪問。點擊 “允許”。
7. 會打開一個瀏覽器窗口，讓你對 Atomic CRM 進行身份驗證並允許 Claude Code 訪問。
8. 身份驗證完成後，你就可以在 Visual Studio Code 中開始使用 Atomic CRM 擴展。

將 MCP 服務器添加到 Claude Desktop

1. 在 Claude Desktop 中導航到設置 > 擴展。
2. 點擊 “添加自定義擴展”。
3. 按如下方式填寫字段：
   • 名稱：Atomic CRM
   • URL：（你的 MCP 服務器 URL，例如 MCP_URL/mcp）
4. 點擊 “添加”。
5. 新擴展現在應該出現在你的擴展列表中。點擊 “連接” 開始使用。
6. 會打開一個瀏覽器窗口，讓你對 Atomic CRM 進行身份驗證並允許 Claude 訪問。
7. 身份驗證完成後，你就可以在 Claude 中開始使用 Atomic CRM 擴展。

將 MCP 服務器添加到 Claude Code

1. 在終端中運行以下命令，將 Atomic CRM MCP 服務器添加到 Claude Code：

   claude mcp add atomic-crm --transport http MCP_URL/mcp
   

2. 打開 Claude Code

   claude
   

3. 列出可用的 MCP 服務器

   /mcp
   

4. atomic-crm 服務器應顯示為 “需要身份驗證”。按 Enter 鍵進行身份驗證。

5. 會打開一個瀏覽器窗口，讓你對 Atomic CRM 進行身份驗證並允許 Claude Code 訪問。

6. 身份驗證完成後，你就可以在 Claude Code 中開始使用 Atomic CRM 擴展。

🔧 技術細節

MCP 工具

• get_schema：檢索數據庫模式，以幫助構建準確的 SQL 查詢，包括用於 JOIN 的外鍵關係。
• query：對 CRM 數據庫執行 SQL 查詢，並實施 RLS。支持包括 JOIN 在內的複雜查詢。

安全機制

• JWT 驗證：所有令牌都根據 Supabase JWKS 進行驗證
• RLS 實施：查詢使用用戶的 JWT 運行，auth.uid() 可在 SQL 中使用
• 會話管理：使用加密安全的會話 ID
• HTTPS 要求：生產環境中必須使用 HTTPS
• 令牌存儲：令牌僅保存在內存中，從不記錄

OAuth 流程

1. MCP 客戶端在未進行身份驗證的情況下連接 → 服務器返回 401 並附帶受保護資源元數據 URL
2. 客戶端從受保護資源元數據中發現 OAuth 端點
3. 客戶端獲取 Supabase 的 OpenID Connect 配置
4. 用戶通過 Supabase（你的 Atomic CRM 身份驗證界面）進行身份驗證
5. 客戶端接收 JWT 訪問令牌
6. 客戶端使用承載令牌進行經過身份驗證的 MCP 請求
7. 服務器根據 Supabase JWKS 驗證 JWT
8. 服務器使用用戶的 JWT 執行查詢以實施 RLS

📚 詳細文檔

故障排除

MCP 服務器連接失敗

• 確保 Supabase 使用 JWT 簽名密鑰（RS256）而不是 JWT 簽名密鑰（HS256） （進入 Supabase 儀表盤 > 設置 > JWT 密鑰） 當前密鑰不應使用 “Legagy HS256 (共享密鑰)” 類型，而應使用 “ECC (P256)” 等類型。

JWT 驗證失敗

• 驗證 Supabase 是否配置為非對稱 JWT 簽名（RS256）
• 檢查 SUPABASE_URL 是否與令牌的 iss 聲明匹配
• 確保在 Supabase 儀表盤中啟用了 OAuth 2.1

數據庫連接失敗

• “未找到租戶或用戶”：你的連接字符串格式不正確。對於直接連接，使用：
  • postgresql://postgres:PASSWORD@db.PROJECT-REF.supabase.co:5432/postgres
  • 不要使用帶有 postgres.PROJECT-REF 或端口 6543 的池化器格式
• 驗證 DATABASE_URL 是否正確且可訪問
• 確保你已將 [YOUR-PASSWORD] 替換為實際的數據庫密碼
• 檢查防火牆規則是否允許從你的服務器進行連接

RLS 阻止查詢

• 檢查 RLS 策略是否允許經過身份驗證的用戶訪問
• 驗證 auth.uid() 是否與預期的用戶 ID 匹配
• 使用服務角色密鑰進行測試以繞過 RLS（僅用於開發）

貢獻代碼

## 在開發模式下運行
npm run dev
## 為生產環境構建
npm run build
npm start
## 類型檢查
npm run typecheck

參考資料

• MCP 規範
• MCP 授權
• Supabase OAuth 服務器
• RFC 9728 - OAuth 受保護資源元數據

📄 許可證

ISC