Twenty MCP

Claude를 Twenty CRM 워크스페이스에 연결하는 원격 MCP(Model Context Protocol) 서버입니다. Cloudflare Workers에 배포되며, 원클릭 팀 설치를 위한 OAuth를 지원합니다.

기능

모든 Twenty 객체(사람, 회사, 기회 또는 사용자 지정 객체)에서 작동하는 9개의 범용 스키마 기반 도구를 제공합니다. MCP는 런타임에 Twenty의 메타데이터 API를 인트로스펙션(introspect)하므로, 필드나 객체를 추가할 때마다 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 — 커넥터 상태 및 현재 범위

Related MCP server: twentycrm-graphql-mcp

설치 (팀원)

1. Claude → 설정 → 커넥터 → 사용자 지정 커넥터 추가

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

3. Claude가 동의 페이지로 리디렉션하면 개인 Twenty API 키가 필요합니다. 키를 얻는 방법:

   • 브라우저에서 Twenty 워크스페이스에 로그인

   • 톱니바퀴 아이콘(왼쪽 하단) 클릭 → 설정

   • 개발자(사이드바의 워크스페이스 섹션 아래)로 이동

   • + API 키 생성을 클릭하고 이름(예: "Claude MCP")을 지정한 후 키를 복사

4. 동의 양식에 API 키를 붙여넣습니다. 권한(읽기 전용 또는 읽기+쓰기)과 선택적 객체 범위를 선택합니다.

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

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

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

사전 요구 사항

• Cloudflare 계정 (무료 플랜 가능)

• Node.js 18 이상

• 실행 중인 Twenty CRM 인스턴스 (자체 호스팅 또는 클라우드)

단계

# 1. Clone the repo
git clone https://github.com/High-Impact-Athletes/hia-twenty-mcp.git
cd hia-twenty-mcp
npm install

# 2. Create the KV namespace
npx wrangler kv namespace create twenty-mcp-oauth
# Note the ID from the output (e.g. "3cd89a10677c4d2ba32c9e59482afa23")

# 3. Create your local config (not committed to git)
cp wrangler.jsonc wrangler.local.jsonc
# Edit wrangler.local.jsonc:
#   - Set "account_id" to your Cloudflare account ID
#   - Replace <OAUTH_KV_ID> with the KV namespace ID from step 2

# 4. Set secrets
npx wrangler secret put COOKIE_ENCRYPTION_KEY --config wrangler.local.jsonc
# Paste the output of: openssl rand -hex 32
# This is just a random string for encrypting OAuth cookies — not a Twenty secret.

npx wrangler secret put TWENTY_BASE_URL --config wrangler.local.jsonc
# Paste your Twenty instance URL, e.g. https://crm.example.com
# This is whatever URL you use to log into Twenty in your browser.

# 5. Deploy
npm run deploy

Worker URL은 https://hia-twenty-mcp.<your-subdomain>.workers.dev가 됩니다. <url>/mcp를 팀과 공유하세요.

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

선택 사항: 관리자 토큰 설정

조직별 프라이머 컨텍스트 업로드를 위한 /admin/* 엔드포인트를 활성화합니다(프라이머 사용자 지정 참조):

npx wrangler secret put ADMIN_TOKEN --config wrangler.local.jsonc
# Paste the output of: openssl rand -hex 32

프라이머 사용자 지정

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

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

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

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

# 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

# Make sure you have wrangler.local.jsonc set up (see Deploy section)
npm run dev            # wrangler dev on http://localhost:8787
npm run typecheck

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

인증 작동 방식

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

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

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

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

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

즉, MCP는 외부(Claude용)로는 OAuth이지만 내부(Twenty용)로는 API 키 방식입니다.

범위 지정

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

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

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

객체 수준 권한은 사용자 API 키에 연결된 역할을 통해 Twenty 자체에서도 적용되므로 이중으로 안전합니다.

Twenty 버전 호환성

Twenty v0.40 이상에서 테스트되었습니다. MCP는 다음을 사용합니다:

• REST API (/rest/<objects>): 레코드 CRUD용 (깊이 0 또는 1로 제한)

• GraphQL 메타데이터 API (/metadata): 스키마 인트로스펙션용 (관계 정보에 대해 Field 타입의 settings 필드 사용)

• 복합 필드(예: name.firstName, emails.primaryEmail)는 필터에서 점 표기법을 사용해야 합니다.

훨씬 이전 버전의 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