CRM管理服务器

🤖 二十CRM MCP服务器

连接 二十CRM 通过模型上下文协议与Claude和AI助手进行交互

通过Claude使用自然语言管理您的CRM数据，并完全支持Twenty的复合字段和GraphQL API。

特性 • 安装 • 用法 • API 参考 • 贡献

✨ 特性

• 🚀 GraphQL原生 -构建于Twenty的GraphQL API之上，用于稳健、类型安全的操作
• 🔄 完全CRUD支持 -创建、阅读、更新和列出人员、公司、机会、任务和笔记
• 🏗️ 复合字段 -正确处理嵌套对象（姓名、电子邮件、电话、地址、链接）
• 💰 货币支持 -交易金额和年度经常性收入的自动转换
• 🔍 智能搜索 -筛选和搜索所有CRM对象
• 📊 销售渠道 -通过阶段、金额和截止日期跟踪机会
• ✅ 任务管理 -创建、分配和跟踪具有状态和截止日期的任务
• 📝 注释操作 -使用富格文本支持添加和管理笔记
• 🔗 关系链接 -将任务和笔记链接到人员、公司和机会
• 📅 时间表活动 -使用完整历史记录跟踪所有交互、事件和更改
• ⭐ 收藏夹管理 -快速访问常用记录
• 📎 附件支持 -上传和管理链接到任何CRM记录的文件
• ⚡ 实时更新 -更改会立即与您的Twenty实例同步
• 🛡️ 类型安全 -具有全面类型定义的完整TypeScript实现
• 🧪 已测试 -具有86+个测试用例的综合单元测试
• 📖 有据可查的 -综合指南和示例

🎯 你能做什么

管理人员：

"Create a contact named Sarah Johnson, email sarah@techco.com, phone +1-555-0100"
"Find all people working at TechCo"
"Update John's job title to Senior Developer"
"List the first 10 contacts in the database"

管理公司：

"Add a company called Acme Corp with website acme.com, 50 employees, and ARR of $2M"
"Show me all companies in San Francisco"
"Update TechStartup's address to 123 Main St, Berlin, Germany"
"List all ideal customer profile companies"

管理机会：

"Create an opportunity called 'Enterprise Deal' for Acme Corp worth €50,000 closing on Dec 31st"
"Show me all opportunities in the MEETING stage"
"Update the Enterprise Deal to PROPOSAL stage with amount €75,000"
"List all opportunities for TechCo"

管理任务：

"Create a task to follow up with Sarah next week with status TODO"
"Show me all IN_PROGRESS tasks"
"Update task to DONE status"
"List all tasks assigned to user-123"

管理笔记：

"Create a note titled 'Meeting Summary' with the key discussion points"
"Show me the note with ID note-456"
"Update the meeting notes with additional information"
"List all notes about the Enterprise Deal"

将任务和注释链接到记录：

"Link task task-123 to person Sarah Johnson"
"Show all tasks linked to Acme Corp"
"Link this note to the Enterprise Deal opportunity"
"Remove the link between task and company"

跟踪时间表活动：

"Create a timeline activity for a call with TechCo"
"Log a meeting event for next Tuesday with Acme Corp"
"Show all timeline activities for Sarah Johnson"
"Update the timeline activity with meeting notes"

管理收藏夹：

"Add Acme Corp to my favorites"
"Show all my favorited companies"
"Add Sarah Johnson to favorites"
"Remove TechCo from favorites"

管理附件：

"Attach the project proposal PDF to task task-123"
"Upload company-logo.png and link it to Acme Corp"
"Show all attachments for the Enterprise Deal opportunity"
"List all IMAGE attachments"
"Find attachments with 'contract' in the name"
"Delete attachment att-456"

🚀 安装

先决条件

• Node.js 18岁或以上
• 二十CRM 实例（自托管或云）
• 克劳德桌面版 或兼容的MCP客户端

选项1：通过npm安装（推荐）

使用此服务器的最简单方法是通过npx：

1. 获取您的Twenty CRM API密钥：

   • 登录您的Twenty CRM实例
   • 导航至 设置→ API和Webhooks （开发商下）
   • 点击 生成API密钥
   • 复制密钥

2. 配置Claude桌面：

   编辑您的 claude_desktop_config.json:

   macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

   复制

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

   对于自托管的Twenty：

   复制

   "TWENTY_BASE_URL": "https://your-twenty-instance.com"
   

3. 重新启动克劳德桌面

选项2：从源代码安装

1. 克隆存储库：

   复制

   git clone https://github.com/KonstiDoll/twenty-crm-mcp-server.git
   cd twenty-crm-mcp-server
   

2. 安装依赖项：

   复制

   npm install
   

3. 构建项目：

   复制

   npm run build
   

4. 获取您的Twenty CRM API密钥：

   • 登录您的Twenty CRM实例
   • 导航至 设置→ API和Webhooks （开发商下）
   • 点击 生成API密钥
   • 复制密钥

5. 配置Claude桌面：

   编辑您的 claude_desktop_config.json:

   macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

   复制

   {
     "mcpServers": {
       "twenty-crm": {
         "command": "node",
         "args": ["/absolute/path/to/twenty-crm-mcp-server/dist/index.js"],
         "env": {
           "TWENTY_API_KEY": "your_api_key_here",
           "TWENTY_BASE_URL": "https://api.twenty.com"
         }
       }
     }
   }
   

   对于自托管的Twenty：

   复制

   "TWENTY_BASE_URL": "https://your-twenty-instance.com"
   

6. 重新启动克劳德桌面

💬 用法

配置后，使用自然语言与CRM交互：

创建记录

人：

"Create a person named Max Mustermann with email max@example.com,
phone +49-123-456789, works at Acme Corp as Software Engineer in Berlin,
LinkedIn: linkedin.com/in/maxmustermann"

公司：

"Create a company called TechStartup GmbH with:
- Website: techstartup.io
- Address: Hauptstraße 123, 10115 Berlin, Germany
- 25 employees
- ARR: €500,000
- Mark as ideal customer profile
- LinkedIn: linkedin.com/company/techstartup"

机会：

"Create an opportunity named 'Q4 Enterprise Deal' for TechStartup:
- Amount: €100,000
- Stage: NEW
- Close date: 2025-12-31
- Point of contact: Max Mustermann"

查询数据

"Show me all people in the CRM"
"List companies with more than 100 employees"
"Find all contacts at Acme Corp"
"Search for people with 'smith' in their name"
"Show all opportunities in MEETING stage"
"List opportunities for TechStartup"

更新记录

"Update Sarah's job title to VP of Engineering"
"Change Acme Corp's employee count to 75"
"Update TechStartup's address city to Munich"
"Move the Enterprise Deal to PROPOSAL stage"
"Update Q4 Enterprise Deal amount to €150,000"

🛠️ API 参考

人员操作

可选人员字段：

• email -主要电子邮件地址
• phone, phoneCountryCode, phoneCallingCode -电话详细信息
• jobTitle -职位名称
• city 城市
• companyId -公司链接
• linkedinUrl, xUrl -社会概况

公司运营

可选公司字段：

• domainUrl -公司网站
• addressStreet1, addressStreet2, addressCity, addressPostcode, addressState, addressCountry -完整地址
• employees -员工人数
• annualRecurringRevenue, currency -ARR（自动转换为微型）
• linkedinUrl, xUrl -社会概况
• idealCustomerProfile -布尔标志

机会运营

可选机会字段：

• amount, currency -交易金额（自动转换为微）
• stage -机会阶段（例如，“新”、“筛选”、“会议”、“提案”、“客户”）
• closeDate -预计结束日期（ISO 8601格式：YYYY-MM-DD）
• companyId -公司链接
• pointOfContactId -联系人链接

列出机会筛选器：

• limit -结果数（最大值：60，默认值：20）
• searchTerm -按商机名称搜索
• companyId -按公司筛选
• stage -按阶段过滤

任务操作

可选任务字段：

• body -任务描述/正文为markdown格式
• status -任务状态：“TODO”、“IN_PROGRESS”、“DONE”（默认值：“TODO”）
• dueAt -到期日（ISO 8601格式：YYYY-MM-DDHH:MM:SSZ）
• assigneeId -要将任务分配给的工作区成员的ID
• personId -自动将任务链接到人员（自动创建任务目标）
• companyId -自动将任务链接到公司（自动创建任务目标）
• opportunityId -自动将任务链接到商机（自动创建任务目标）

列出任务筛选器：

• limit -结果数（最大值：60，默认值：20）
• searchTerm -按任务标题搜索
• status -按状态筛选（“TODO”、“IN_PROGRESS”、“DONE”）
• assigneeId -按受让人筛选

注释操作

可选注释字段：

• body -以markdown格式记录正文/内容
• personId -自动将笔记链接到人（自动创建笔记目标）
• companyId -自动将钞票链接到公司（自动创建钞票目标）
• opportunityId -自动将备注链接到商机（自动创建备注目标）

列表注释筛选器：

• limit -结果数（最大值：60，默认值：20）
• searchTerm -按笔记标题搜索

任务目标操作

任务目标字段：

• taskId -要链接的任务ID（必需）
• personId -将任务链接到的人员ID
• companyId -将任务链接到的公司ID
• opportunityId -将任务链接到的机会ID

注： 必须至少提供一个目标（personId、companyId或opportunityId）。

列出任务目标筛选器：

• taskId -按任务ID筛选（显示链接到此任务的所有实体）
• personId -按人员ID筛选（显示链接到此人员的所有任务）
• companyId -按公司ID筛选（显示链接到此公司的所有任务）
• opportunityId -按商机ID筛选（显示与此商机链接的所有任务）
• limit -结果数（最大值：60，默认值：20）

注意目标操作

注意目标字段：

• noteId -要链接的注释ID（必需）
• personId -用于将笔记链接到的个人ID
• companyId -用于将注释链接到的公司ID
• opportunityId -将注释链接到的机会ID

注： 必须至少提供一个目标（personId、companyId或opportunityId）。

列出注释目标筛选器：

• noteId -按笔记ID筛选（显示链接到此笔记的所有实体）
• personId -按人员ID筛选（显示链接到此人员的所有笔记）
• companyId -按公司ID筛选（显示链接到此公司的所有笔记）
• opportunityId -按商机ID筛选（显示链接到此商机的所有备注）
• limit -结果数（最大值：60，默认值：20）

时间线活动操作

时间线活动字段：

• name -活动名称/标题（必填）
• properties -带有活动详细信息的JSON对象（例如，{类型：“CALL”，注释：“已讨论定价”}）
• happensAt -活动发生时（ISO 8601格式）
• workspaceMemberId -与此活动关联的工作区成员的ID
• personId -与此活动关联的人员ID
• companyId -与此活动关联的公司ID
• opportunityId -与此活动关联的机会ID
• noteId -与此活动关联的注释ID
• taskId -与此活动关联的任务ID
• linkedRecordId -链接记录ID
• linkedObjectMetadataId -链接对象元数据ID
• linkedRecordCachedName -链接记录的缓存名称

列出时间线活动筛选器：

• limit -结果数（最大值：60，默认值：20）
• searchTerm -按活动名称搜索
• personId -按人员ID筛选
• companyId -按公司ID筛选
• opportunityId -按商机ID筛选
• workspaceMemberId -按工作区成员ID筛选
• noteId -按钞票ID筛选
• taskId -按任务ID筛选

最喜欢的操作

最喜欢的字段：

• personId -要添加到收藏夹的个人ID
• companyId -要添加到收藏夹的公司ID
• opportunityId -要添加到收藏夹的机会ID
• position -收藏夹列表中的位置（可选）

注： 必须至少为提供一个目标（personId、companyId或opportunityId） add_favorite.

列出收藏夹筛选器：

• limit -结果数（最大值：60，默认值：20）
• personId -按人员ID筛选
• companyId -按公司ID筛选
• opportunityId -按商机ID筛选
• workspaceMemberId -按工作区成员ID筛选

附件操作

附件字段：

• name -附件名称/文件名（必填）
• fullPath -文件的完整路径或URL（必填）
• fileCategory -文件类别：“档案”、“音频”、“图像”、“演示文稿”、“幻灯片”、“文本文档”、“视频”、“其他”
• taskId -要将文件附加到的任务ID
• opportunityId -要将文件附加到的机会ID
• companyId -要将文件附加到的公司ID
• personId -要将文件附加到的个人ID
• workflowId -要将文件附加到的工作流ID
• dashboardId -要将文件附加到的仪表板ID
• authorId -作者ID（创建附件的工作区成员）

注： 必须为提供至少一个关系ID（任务ID、公司ID、人员ID、机会ID、工作流ID或仪表板ID） create_attachment.

列出附件筛选器：

• limit -结果数（最大值：60，默认值：20）
• searchTerm -按附件名称搜索
• fileCategory -按文件类别筛选
• taskId -按任务ID筛选（显示此任务的附件）
• opportunityId -按商机ID筛选（显示此商机的附件）
• companyId -按公司ID筛选（显示此公司的附件）
• personId -按人员ID筛选（显示此人的附件）
• workflowId -按工作流ID筛选（显示此工作流的附件）
• dashboardId -按仪表板ID筛选（显示此仪表板的附件）
• authorId -按作者ID（工作区成员）筛选

📋 理解复合字段

20种CRM应用 复合油田 相关数据。此服务器自动处理它们：

名称复合

name: {
  firstName: "John",
  lastName: "Doe"
}

电子邮件合成

emails: {
  primaryEmail: "john@example.com",
  additionalEmails: ["john.doe@gmail.com"]
}

手机复合材料

phones: {
  primaryPhoneNumber: "5551234567",
  primaryPhoneCountryCode: "US",
  primaryPhoneCallingCode: "+1",
  additionalPhones: []
}

地址综合

address: {
  addressStreet1: "123 Main St",
  addressStreet2: "Suite 100",
  addressCity: "San Francisco",
  addressPostcode: "94102",
  addressState: "CA",
  addressCountry: "United States"
}

链接组合（LinkedIn、X、域名）

linkedinLink: {
  primaryLinkUrl: "https://linkedin.com/in/user",
  secondaryLinks: []
}

货币综合（ARR）

annualRecurringRevenue: {
  amountMicros: 5000000000000,  // $5M stored as micros
  currencyCode: "USD"
}

注： 您提供简单的值（例如。， email: "john@example.com")，并且服务器自动为Twenty的API正确构建它们。

🏗️ 建筑

为什么选择GraphQL？

此服务器使用 图查询语言 而不是REST，因为：

1. 更适合嵌套对象 -二十使用许多复合字段
2. 类型安全性 -GraphQL模式验证及早发现错误
3. 灵活的查询 -请求您需要的字段
4. 清除错误消息 -更容易调试
5. 经得起未来考验 -易于扩展新领域

技术栈

• MCP-SDK - @模型上下文协议/sdk
• 图查询语言 -与Twenty的GraphQL API直接集成
• Node.js -ES模块，异步/等待
• TypeScript -全类型安全和IDE支持
• 维测试 -快速单元测试，代码覆盖率超过71%
• 二十CRM -开源CRM平台

🧪 开发与测试

TypeScript支持

服务器已写入 TypeScript 具有以下全面的类型定义：

• 所有API操作 -个人和公司CRUD操作
• GraphQL请求 -查询和突变的完整打字
• 复合字段 -类型安全的嵌套对象
• MCP协议 -与SDK的类型系统集成

优点：

• 🔒 具有自动补全功能的类型安全开发
• 🐛 在编译时捕获错误
• 📖 具有IntelliSense的自文档化代码
• 🔄 轻松自信地重构

从源头构建

# Build the TypeScript code
npm run build

# Start the compiled server
npm start

# Development mode with auto-reload
npm run dev

# Type-check without building
npm run type-check

运行测试

该项目包括 综合单元测试 代码覆盖率超过71%：

# Run all tests
npm test

# Watch mode for development
npm run test:watch

# Generate coverage report
npm run test:coverage

测试覆盖范围：

• ✅ GraphQL请求处理
• ✅ 所有Person操作（创建、获取、列表、更新）
• ✅ 公司所有操作（创建、获取、列出、更新）
• ✅ 所有Opportunity操作（创建、获取、列出、更新）
• ✅ 所有任务操作（创建、获取、列出、更新）
• ✅ 所有注释操作（创建、获取、列出、更新）
• ✅ 错误处理和验证
• ✅ 复合字段转换（姓名、电子邮件、电话、地址、bodyV2）
• ✅ 货币转换（ARR和机会金额为微）

配置文件

TypeScript：

• tsconfig.json -TypeScript编译器配置
• src/index.ts -主服务器实现

测试：

• vitest.config.ts -测试配置
• src/index.test.ts -全面的测试套件

构建输出：

• dist/ -编译的JavaScript和类型定义
• coverage/ -测试覆盖率报告

🐛 故障排除

连接问题

错误：GraphQL请求失败（404）

• 检查 TWENTY_BASE_URL 是正确的
• 自托管：使用您的完整域名（例如。， https://twenty.company.com)
• 云：使用 https://api.twenty.com
• GraphQL端点自动设置为 ${TWENTY_BASE_URL}/graphql

错误：GraphQL请求失败（401）或（403）

• 验证API密钥是否正确
• 在二十中检查API密钥是否具有适当权限
• 在“设置”中生成新的API密钥→ API和Webhooks

字段验证错误

错误： Field 'xyz' expected type 'ABC'

服务器自动处理字段转换。如果您看到验证错误：

1. 检查字段名称是否与API引用匹配
2. 确保数据类型正确（字符串、数字、布尔值）
3. 查看GraphQL错误消息以了解详细信息
4. 查看示例部分以了解正确用法

记录未显示

症状： 无错误，但记录未出现在Twenty UI中

调试步骤：

1. 检查回复-是否包括 id?
2. 尝试按ID提取： "Get person with ID xyz"
3. 刷新Twenty CRM用户界面
4. 检查Claude Desktop日志中隐藏的错误

🔄 常见工作流

新客户入职

1. "Create a company called NewCo with domain newco.com"
2. "Create a person named John Smith, email john@newco.com, works at NewCo as CTO"
3. "Update NewCo's details: 10 employees, ARR $250k, mark as ideal customer profile"

潜在客户管理

1. "List all ideal customer profile companies"
2. "Find all contacts at [company name]"
3. "Update [person] with note about last call"

数据丰富

1. "List people without LinkedIn profiles"
2. "Update [person] LinkedIn: linkedin.com/in/username"
3. "List companies missing employee count"

🤝 贡献

我们欢迎捐款！以下是如何提供帮助：

报告问题

1. 先检查现有问题
2. 提供清晰的复制步骤
3. 包括错误消息
4. 分享你的Twenty版本

提交PR

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 进行更改
4. 针对真实的Twenty实例进行测试
5. 以明确的信息提交
6. 推送并创建拉取请求

开发环境

# Clone your fork
git clone https://github.com/your-username/twenty-crm-mcp-server.git
cd twenty-crm-mcp-server

# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Edit .env with your API key

# Build the TypeScript code
npm run build

# Run tests
npm test

# Test changes in development mode
npm run dev

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• 二十CRM -优秀的开源CRM平台
• Anthropic -模型上下文协议规范
• MCP社区 -灵感与支持

🔗 链接

• 二十CRM
• 二十份文件
• 模型上下文协议
• 克劳德桌面版
• GitHub问题

🚀 后续步骤

准备好扩展此服务器了吗？以下是一些想法：

已完成的功能

• [x] 机会跟踪 -销售渠道管理✅ v0.2.0版本
• [x] 任务管理 -创建、分配和跟踪任务✅ v0.4.0
• [x] 注释操作 -添加和管理笔记✅ v0.4.0
• [x] 关系链接 -将任务/笔记链接到人员、公司、机会✅ v0.5.0
• [x] 时间线和收藏夹 -活动跟踪和快速访问✅ v0.5.0
• [x] 附件 -与任何记录链接的文件管理✅ v0.6.0

计划的功能

• [ ] 自定义字段 -支持特定于工作区的字段
• [ ] 批量操作 -批量创建/更新记录
• [ ] 网络钩子 -实时通知
• [ ] 高级过滤器 -复杂查询构建
• [ ] 导出/导入 -CSV/JSON数据操作
• [ ] 分析 -查询见解和指标

想贡献吗？

从上面的列表中选择一个功能，或者建议你自己的功能！ 打开一个问题进行讨论，然后提交一份PR。

制作❤️ 面向开源社区

⭐ 如果你觉得这个仓库有用，就把它标上！

报告Bug · 请求功能 · 讨论