Custify MCP

🚀 @custify/mcp-server

💡 通過 模型上下文協議（Model Context Protocol） 將你的 AI 工具連接到 Custify 客戶成功數據。

查詢賬戶、健康分、使用數據等 —— 或創建筆記、任務、觸發劇本 —— 全部可以在 Claude、Cursor、VS Code 或任何兼容 MCP 的 AI 工具中完成。

🚀 快速開始

不到 2 分鐘即可完成上手。

1️⃣ 獲取 API 密鑰

前往 Custify Settings > Developer > API Access，創建或複製你的 API 密鑰。

2️⃣ 安裝

npx @custify/mcp-server

3️⃣ 配置你的 AI 工具

請參考下方的 配置 章節，找到你所用工具的說明。

4️⃣ 試用

向你的 AI 助手提問：

我有多少流失賬戶？

⚙️ 配置

{
  "mcpServers": {
    "custify": {
      "command": "npx",
      "args": ["-y", "@custify/mcp-server"],
      "env": {
        "CUSTIFY_API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "servers": {
    "custify": {
      "command": "npx",
      "args": ["-y", "@custify/mcp-server"],
      "env": {
        "CUSTIFY_API_KEY": "your-api-key-here"
      }
    }
  }
}

claude mcp add custify -- npx -y @custify/mcp-server \
  --env CUSTIFY_API_KEY=your-api-key-here

docker run -d \
  -p 3000:3000 \
  -e CUSTIFY_API_KEY=your-api-key-here \
  ghcr.io/custifyofficial/custify-mcp:latest

https://your-server.example.com/mcp

🧰 可用工具

🏢 賬戶工具

list_accounts 支持使用 tag_ids 進行簡單的 tag 篩選，也支持 Custify 完整的過濾器系統用於高級字段。使用 list_tags 並傳入 category: "company" 可將賬戶 tag 名稱解析為 ID。使用 list_attributes 並傳入 entity_type: "account" 可發現可用字段。

當通過 filters 手動傳入時，tag 過濾器使用以下後端格式：

{
  "fieldName": "tags",
  "fieldType": "Tag",
  "filterType": "is_any_of",
  "filterValue": ["<company_tag_id>"]
}

支持的 tag filterType 值為 is_any_of、is_all_of、is_none_of、is_unknown 和 any_value。對於基於 ID 的 tag 過濾器，filterValue 必須是非空的 tag ID 數組。

過濾器示例：

按字段類型可用的過濾類型：

👥 聯繫人工具

list_contacts 是 list_accounts 在聯繫人層面的對應工具。使用 tag_ids 配合 people tag 進行簡單 tag 篩選，或傳入 Custify 高級過濾器。使用 list_tags 並傳入 category: "people" 可將聯繫人 tag 名稱解析為 ID。使用 list_attributes 並傳入 entity_type: "contact" 可發現可用的聯繫人字段。

聯繫人過濾器示例：

📊 健康與使用工具

🔔 告警與分群

✅ 任務工具

list_tasks 使用扁平、易用的參數。過濾器之間以 AND 組合。要將 "onboarding follow up" 這類 tag 名稱解析為 ID，請調用 list_tags 並傳入 category: "task"。要解析負責人名稱，請調用 list_task_filter_values（返回帶名稱的用戶 ID）。

過濾器示例：

可用的狀態過濾值：

update_task_status 只會寫入持久化的任務狀態：open、done 和 not_relevant。請先使用 list_tasks 找到內部 task_id，然後攜帶新狀態調用 update_task_status。

可用的 due 快捷值： past_due、today、this_week、this_month、later。如需自定義範圍，請同時提供 due_after 和 due_before（ISO 日期）。due 快捷方式與日期範圍組合互斥 —— 只傳入其中一個邊界將被忽略。

🎯 目標工具

get_account_objectives 接受 account_id（Custify 內部公司 ID）或 external_account_id（你的 company_id）。它支持分頁、排序，以及針對 objectiveStatus、importance、risk、dueAt 等字段的 Custify 過濾器對象。

⚡ 操作工具

Tag 操作接受 entity_type: "account" 或 entity_type: "contact"、一個 Custify 內部 entity_ids 數組和一個 tag_id。請先使用 list_tags 或 custify://tags 資源將 tag 名稱解析為 ID。

📚 可用資源

資源為 AI 代理提供只讀上下文，用於理解你的 Custify 工作區：

💡 示例

以下是連接後你可以向 AI 助手提出的真實場景示例：

查詢賬戶

"我有多少流失賬戶？" 使用 list_accounts 配合 churned 過濾器，統計 churned = true 的賬戶數量。

"顯示所有健康分低於 30 的賬戶" 使用 list_attributes 找到健康分字段名，然後使用 list_accounts 配合 Number 過濾器。

"找出所有由 jane@company.com 管理的賬戶" 使用 list_accounts 在 CSM 字段上配合 User 過濾器。

"哪些賬戶是在本季度註冊的？" 使用 list_accounts 配合 Date 過濾器：在 signed_up_at 上設置 filterType: "this_quarter"。

"顯示標記為 renewal risk 的賬戶" 使用 list_tags 並傳入 category: "company" 解析 tag ID，然後使用 list_accounts 配合 tag_ids。

查詢聯繫人

"顯示標記為 champion 的聯繫人" 使用 list_tags 並傳入 category: "people" 解析 tag ID，然後使用 list_contacts 配合 tag_ids。

"找出使用 example.com 郵箱的聯繫人" 使用 list_contacts 在 email 上配合 String 過濾器。

賬戶深度分析

"給我一份 Acme Corp 的完整摘要" 使用 search_accounts 找到 Acme，然後通過 get_account、get_health_scores、get_contacts、get_usage_data 和 get_segment_membership 構建一份全面的簡報。

"Acme Corp 屬於哪些分群？" 使用 search_accounts 找到賬戶 ID，然後使用 get_segment_membership。

"顯示 Acme Corp 上個月的健康分趨勢" 使用 get_health_scores 找到分數 ID，然後使用 get_usage_trends 獲取歷史數值。

查詢任務

"我今天有什麼任務？" 使用 list_tasks 配合 assignee_id（你的用戶 ID）和 due: "today"，拉取每日任務清單。

"顯示所有分配給 Jane、標記為 'onboarding follow up' 的逾期任務" 使用 list_tags 並傳入 category: "task" 將 tag 名稱解析為 ID，用 list_task_filter_values 解析 Jane 的用戶 ID，然後使用 list_tasks 配合 tag_ids、assignee_id 和 status: "overdue"。

"Acme Corp 有哪些未完成的任務？" 使用 search_accounts 找到賬戶 ID，然後使用 list_tasks 配合 account_id 和 status: "open"。

"把 onboarding review 任務標記為已完成" 使用 list_tasks 找到匹配的任務 ID，然後使用 update_task_status 並傳入 status: "done"。使用 status: "open" 可重新打開任務，使用 status: "not_relevant" 可將其標記為不相關。

查詢目標

"Acme Corp 有哪些未完成的目標？" 使用 search_accounts 找到賬戶 ID，然後使用 get_account_objectives。

執行操作

"為 Acme Corp 創建一條跟進任務：Review onboarding progress，下週五到期" 使用 search_accounts 找到 Acme，然後使用 create_task 並傳入標題、到期日和賬戶 ID。

"給 Acme Corp 添加一條筆記：Spoke with VP of Engineering about API latency concerns" 使用 search_accounts，然後使用 create_note 並傳入筆記正文。

"為 Acme Corp 運行 renewal prep 劇本" 使用 playbooks 資源找到劇本 ID，用 search_accounts 找到賬戶，然後使用 run_playbook。

"把 Acme Corp 標記為 renewal risk" 使用 search_accounts 找到賬戶 ID，用 list_tags 或 custify://tags 找到 tag ID，然後使用 add_tag_to_entities。

探索你的數據模型

"我可以按哪些字段篩選賬戶？" 使用 list_attributes 返回所有可用字段及其名稱和類型。

"我們有哪些分群？" 讀取 custify://segments 資源。

"有哪些可用的劇本？" 讀取 custify://playbooks 資源。

"我們有哪些計算指標和生命週期階段？" 讀取 custify://calculated-metrics 和 custify://lifecycles 資源。

"我可以在賬戶和聯繫人上使用哪些 tag？" 讀取 custify://tags 資源。

🔐 環境變量

🐳 Docker

以 Docker 容器方式運行服務器，用於基於 HTTP 的 MCP 客戶端：

docker run -d \
  --name custify-mcp \
  -p 3000:3000 \
  -e CUSTIFY_API_KEY=your-api-key-here \
  ghcr.io/custifyofficial/custify-mcp:latest

MCP 端點將位於 http://localhost:3000/mcp，健康檢查端點位於 http://localhost:3000/health。

🛡️ 安全

• 數據流： 你的 AI 工具與 Custify MCP 服務器通信，後者再向 Custify REST API 發起經過認證的調用。MCP 服務器本身不存儲任何數據。
• API 密鑰處理： 你的 CUSTIFY_API_KEY 從環境變量中讀取，絕不會被記錄、緩存或通過 MCP 響應暴露。使用 STDIO 傳輸時，密鑰保留在你的本地進程中。使用 HTTP 傳輸時，請確保你的部署位於 TLS 之後。
• 權限： MCP 服務器繼承你的 API 密鑰所擁有的權限。請使用一個僅具備工作流所需最低訪問級別的密鑰。只讀密鑰可用於所有讀取工具；寫入工具需要具備寫入權限的密鑰。
• 無遙測： 服務器不收集分析數據，也不向任何第三方發送數據。

🧯 故障排查

"Error: CUSTIFY_API_KEY environment variable is required" 請確保在你的 MCP 客戶端配置中設置了 CUSTIFY_API_KEY 環境變量。仔細檢查是否有拼寫錯誤，並確保沒有多餘的空格。

Claude Desktop 中服務器無法連接

1. 確認配置文件路徑與你的操作系統匹配。
2. 確保在編輯配置後已重啟 Claude Desktop。
3. 檢查 npx 是否在系統 PATH 中可用。

認證錯誤（401） 你的 API 密鑰可能無效或已過期。請前往 Custify Settings > Developer > API Access 生成一個新的密鑰。

權限錯誤（403） 該端點可能不允許通過 API 密鑰訪問。請檢查你的 Custify 賬戶是否具備所需權限。

超時或連接錯誤 如果使用 HTTP 傳輸，請確認服務器正在運行且可訪問。檢查 PORT 環境變量是否與你的部署配置匹配。對於 STDIO 傳輸，請確保沒有防火牆或代理阻止本地進程通信。

使用不同的 Custify 集群？ 如果你的 Custify 實例位於不同集群（例如 EU），請將 CUSTIFY_API_URL 設置為你的集群 API URL。

Docker 容器立即退出 使用 docker logs custify-mcp 檢查容器日誌。最常見的原因是缺少 CUSTIFY_API_KEY 環境變量。

🤝 貢獻

歡迎貢獻！要開始參與：

git clone https://github.com/CustifyOfficial/custify-mcp.git
cd custify-mcp-server
npm install
npm run dev

1. Fork 本倉庫
2. 創建功能分支：git checkout -b feature/my-feature
3. 進行修改並添加測試
4. 運行測試套件：npm test
5. 提交 pull request

如果你計劃進行重大修改，請先開一個 issue。

📄 許可證

MIT —— 詳情請見 LICENSE。