mhenry3164/twenty-crm-mcp-server

将你的CRM转变为AI驱动的助手

一台模型上下文协议服务器，连接Twenty CRM、Claude及其他AI助手，实现与客户数据的自然语言交互。

🚀 快速入门 • 🛠️ 工具 • 🔍 搜索与筛选 • 🐳 Docker • 🤝 贡献

---

✨ 特色

• 完成人员、公司、机会、笔记和任务的CRUD
• 工作搜索 — 基于Twenty的真实filter语法（ilike匹配），而非不存在的search参数
• 正确的复合场映射 — 像 firstName/email/amount 在写入时转换为二十个 name/emails/amount 的复合形状
• 光标分页 （startingAfter/[endingBefore）加上所有列表工具上的原始 filter、orderBy 和 depth 直通
• 笔记和任务附加到记录 — 创建时传递 personId/companyId/opportunityId，目标链接会为你创建
• 批量创建 — 每次通话最多60人或公司
• 弹性客户端 — 30秒超时，自动重试并429/5xx退回（荣誉Retry-After），结构化错误信息

---

✨ Features

• Complete CRUD for people, companies, opportunities, notes and tasks
• Working search — built on Twenty’s real filter grammar (ilike matching), not the nonexistent search param
• Correct composite-field mapping — flat inputs like firstName/email/amount are converted to Twenty’s name/emails/amount composite shapes on write
• Cursor pagination (startingAfter/endingBefore) plus raw filter, orderBy and depth passthrough on every list tool
• Notes & tasks attach to records — pass personId/companyId/opportunityId when creating and the target links are created for you
• Batch creates — up to 60 people or companies per call
• Resilient client — 30s timeouts, automatic retry with backoff on 429/5xx (honors Retry-After), structured error messages
• Schema discovery — metadata tools expose your workspace’s objects, fields and enum options, including custom objects

🚀 Installation

Prerequisites

• Node.js 18 or higher
• A Twenty CRM instance (cloud or self-hosted)
• Claude Desktop, Claude Code, or any MCP-compatible client

Setup

1. Get your Twenty CRM API key: in Twenty, go to Settings → API & Webhooks (under Developers) and generate a key.

2. Configure your MCP client.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "twenty-crm": {
      "command": "npx",
      "args": ["-y", "github:mhenry3164/twenty-crm-mcp-server"],
      "env": {
        "TWENTY_API_KEY": "your_api_key_here",
        "TWENTY_BASE_URL": "https://api.twenty.com"
      }
    }
  }
}

Claude Code:

claude mcp add twenty-crm -e TWENTY_API_KEY=your_api_key_here -e TWENTY_BASE_URL=https://api.twenty.com -- npx -y github:mhenry3164/twenty-crm-mcp-server

Or clone and run from source:

git clone https://github.com/mhenry3164/twenty-crm-mcp-server.git
cd twenty-crm-mcp-server
npm install