mhenry3164/twenty-crm-mcp-server

CRM을 AI 기반 비서로 변환하세요

Twenty CRM과 Claude 및 기타 AI 어시스턴트를 연결하여 고객 데이터와 자연어로 상호작용할 수 있게 하는 모델 컨텍스트 프로토콜 서버입니다.

🚀 빠른 시작 • 🛠️ 도구 • 🔍 검색 및 필터링 • 🐳 도커 • 🤝 기여하기

---

✨ 특징

• 사람, 회사, 기회, 노트 및 작업에 대한 완전한 CRUD
• 작업 중인 검색 — Twenty의 실제 [filter 문법([ilike 매칭)을 기반으로 구축되었으며, 존재하지 않는 search 파라미터가 아닙니다
• 올바른 복합 필드 매핑 — firstName/email/amount 같은 평면 입력은 쓰기 시 20개의 name/emails/[amount 합성 도형으로 변환됩니다
• 커서 페이지네이션 (startingAfter/endingBefore)와 모든 리스트 도구에서 원시 filter, orderBy, depth 패스스루
• 노트 및 작업이 기록에 부착됨 — 생성할 때 personId/companyId/[[[T16]를 통과시키면 대상 링크가 생성됩니다
• 배치 생성 — 통화당 최대 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