Twenty MCP

Claude를 Twenty CRM 워크스페이스에 연결하는 원격 MCP(Model Context Protocol) 서버입니다. Cloudflare Workers에 배포되며 OAuth를 통해 팀 단위로 간편하게 설치할 수 있습니다.

기능

모든 Twenty 객체(사람, 회사, 기회 또는 사용자 지정 객체)에서 작동하는 8개의 범용 스키마 기반 도구를 제공합니다. MCP는 런타임에 Twenty의 메타데이터 API를 내부적으로 검사하므로, 필드나 객체를 추가할 때마다 MCP를 업데이트할 필요가 없습니다.

도구

• list_objects, describe_object — CRM 내의 항목 탐색

• find_records, get_record — 필터/정렬/페이지네이션을 사용한 쿼리

• create_record, update_record, delete_record — 데이터 변경(쓰기 모드로 연결된 경우에만 가능)

• run_graphql — 원시 메타데이터/GraphQL을 위한 탈출구

• get_primer — 조직별 도메인 컨텍스트 + 실시간 스키마 스냅샷

리소스 (세션 시작 시 Claude가 자동 로드)

• twenty://primer — 조직 컨텍스트와 압축된 스키마 스냅샷이 병합된 데이터

• twenty://api/info — 커넥터 상태 및 현재 범위

설치 (팀원, 원클릭)

1. Claude → 설정 → 커넥터 → 사용자 지정 커넥터 추가로 이동합니다.

2. URL: https://<your-worker>.workers.dev/mcp 입력

3. Claude가 동의 페이지로 리디렉션합니다. 개인 Twenty API 키(Twenty → 설정 → 개발자 → API 키 생성)를 붙여넣습니다.

4. 권한(읽기 전용 또는 읽기+쓰기)과 선택적 객체 범위를 선택합니다.

5. 완료되었습니다. 키는 암호화되어 Cloudflare KV에 저장되며 세션에 바인딩됩니다.

Twenty에서 수행한 변경 사항은 공유 서비스 계정이 아닌 사용자의 Twenty 계정으로 기록됩니다.

배포 (관리자, 최초 설정)

1. 위의 배포 버튼을 클릭합니다. Cloudflare가 저장소를 포크하고 보안 정보를 요청합니다.

2. 필수 보안 정보를 설정합니다:

   • COOKIE_ENCRYPTION_KEY — openssl rand -hex 32

   • TWENTY_BASE_URL — Twenty 인스턴스 URL (예: https://crm.example.com)

3. (선택 사항) ADMIN_TOKEN 설정 — openssl rand -hex 32 — 프라이머 관리를 위한 /admin/* 엔드포인트를 활성화합니다.

4. 배포된 URL(예: https://twenty-mcp.your-subdomain.workers.dev)을 기록해 둡니다.

5. <url>/mcp를 팀원들과 공유합니다.

Claude 관리형 팀의 경우: Claude 팀 관리 콘솔에 <url>/mcp를 한 번 등록하면 모든 팀원의 커넥터 목록에 나타납니다. 각 팀원은 자신의 Twenty API 키를 붙여넣기 위해 일회성 동의 페이지를 완료해야 합니다.

프라이머 사용자 지정

twenty://primer 리소스는 도구 호출 전에 Claude에게 CRM에 대한 컨텍스트를 제공합니다. 여기에는 두 가지 부분이 포함됩니다.

1. 조직 컨텍스트 — 도메인 모델, 사용자 지정 객체, 비즈니스 규칙 및 관례를 설명하는 마크다운 문서입니다. 내부 검사로 파악할 수 없는 정보(예: "객체 A와 객체 B는 독립적이므로 하나를 통해 다른 하나를 추론하지 마십시오")를 포함합니다.

2. 스키마 스냅샷 — Twenty의 메타데이터 API에서 자동 생성되며 1시간 동안 캐시됩니다.

기본적으로 (1)번 부분은 일반적인 Twenty 템플릿입니다. 조직별 컨텍스트를 업로드하려면 다음을 수행하세요:

# Set ADMIN_TOKEN first if you haven't:
# wrangler secret put ADMIN_TOKEN

# Upload your context markdown:
curl -X PUT https://<your-worker>.workers.dev/admin/primer \
  -H "Authorization: Bearer <your-admin-token>" \
  -H "Content-Type: text/markdown" \
  --data-binary @path/to/your-context.md

# Verify it's loaded:
curl https://<your-worker>.workers.dev/admin/primer \
  -H "Authorization: Bearer <your-admin-token>"

# Revert to the bundled default:
curl -X DELETE https://<your-worker>.workers.dev/admin/primer \
  -H "Authorization: Bearer <your-admin-token>"

컨텍스트 마크다운에는 조직의 업무, 각 사용자 지정 객체의 의미와 관계, 계층/분류 모델, 명명 규칙, AI를 위한 "수행할 작업 / 수행하지 말아야 할 작업" 규칙이 설명되어 있어야 합니다. 템플릿 구조는 src/primer/default-context.md를 참조하세요.

로컬 개발

npm install
cp .dev.vars.example .dev.vars
# edit .dev.vars — set COOKIE_ENCRYPTION_KEY, TWENTY_BASE_URL, and optionally ADMIN_TOKEN
npm run dev            # wrangler dev on http://localhost:8787
npm run typecheck

로컬 Claude Desktop을 개발용 워커에 연결하려면 http://localhost:8787/mcp를 커넥터로 추가하세요.

인증 작동 방식

Twenty에는 업스트림 OAuth 제공자가 없으며, 워크스페이스별 API 키를 통해 인증합니다. 따라서:

• 워커는 자체 OAuth 2.1 엔드포인트를 실행합니다(Claude 커넥터에 필요).

• OAuth 동의 단계에서 사용자는 Twenty API 키를 HTML 폼에 붙여넣습니다.

• 워커는 Twenty의 /metadata 엔드포인트에 대해 키를 검증한 다음 {twentyApiKey, mode, allowedObjects, label}을 암호화된 OAuth 속성으로 저장합니다.

• 이후의 모든 MCP 도구 호출은 this.props를 통해 사용자의 키를 사용할 수 있습니다.

즉, MCP는 외부(Claude용)로는 OAuth를 사용하고 내부(Twenty용)로는 API 키를 사용합니다.

범위 지정

각 연결은 설치 시 제한할 수 있습니다:

• 모드: 읽기 전용은 create_record / update_record / delete_record를 숨깁니다.

• 허용된 객체: 특정 객체로 제한하기 위한 쉼표로 구분된 목록입니다.

객체 수준 권한은 사용자의 API 키에 연결된 역할을 통해 Twenty 자체에서도 적용됩니다(이중 보안).

아키텍처

Claude ↔ OAuth 2.1 ↔ Worker ↔ REST+GraphQL ↔ Twenty workspace
                        │
                        ├─ McpAgent Durable Object (per session)
                        ├─ OAUTH_KV (token store, schema cache, primer)
                        └─ twenty://primer (org context + live schema)

라이선스

Apache-2.0. fathom-mcp와 동일한 아키텍처를 기반으로 합니다.