Twenty MCP

Удаленный MCP-сервер (Model Context Protocol), который подключает Claude к рабочему пространству Twenty CRM, развернутый на Cloudflare Workers с OAuth для установки командой в один клик.

Что он делает

Предоставляет 8 универсальных инструментов, управляемых схемой, которые работают с любым объектом Twenty (человек, компания, сделка или любой пользовательский объект). MCP анализирует метаданные API Twenty во время выполнения — вам никогда не нужно обновлять 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 — статус коннектора и текущие области действия (scopes)

Установка (для члена команды, в один клик)

1. В Claude → Настройки → Коннекторы → Добавить пользовательский коннектор

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

3. Claude перенаправит вас на страницу согласия. Вставьте свой личный API-ключ Twenty (из Twenty → Настройки → Разработчикам → Создать API-ключ).

4. Выберите права доступа (только чтение или чтение+запись) и дополнительные области действия объектов.

5. Готово. Ваш ключ хранится в зашифрованном виде в Cloudflare KV и привязан к вашей сессии.

Изменения, которые вы вносите в Twenty, приписываются вашему пользователю Twenty, а не общей сервисной учетной записи.

Развертывание (для администратора, первый раз)

1. Нажмите кнопку развертывания выше. Cloudflare создаст форк репозитория и запросит секреты.

2. Установите необходимые секреты:

   • COOKIE_ENCRYPTION_KEY — openssl rand -hex 32

   • TWENTY_BASE_URL — URL вашего экземпляра Twenty (например, 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: зарегистрируйте <url>/mcp один раз в консоли администратора команды Claude — он появится в списке коннекторов каждого члена команды. Каждый участник все равно должен пройти однократную страницу согласия, чтобы вставить свой собственный API-ключ Twenty.

Настройка праймера

Ресурс twenty://primer дает Claude контекст о вашей CRM перед любыми вызовами инструментов. Он состоит из двух частей:

1. Контекст организации — документ в формате markdown, описывающий вашу модель домена, пользовательские объекты, бизнес-правила и соглашения. То, что интроспекция не может уловить (например, «Объект А и Объект Б независимы — не делайте выводов об одном на основе другого»).

2. Снимок схемы — автоматически генерируется из API метаданных Twenty, кэшируется на 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>"

Контекст в формате markdown должен описывать: чем занимается ваша организация, что означает каждый пользовательский объект и как они связаны, модели уровней/классификации, соглашения об именовании и любые правила «делай это / не делай то» для ИИ. См. 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 пользователь вставляет свой API-ключ Twenty в HTML-форму.

• Воркер проверяет ключ через эндпоинт /metadata в Twenty, а затем сохраняет {twentyApiKey, mode, allowedObjects, label} как зашифрованные свойства OAuth.

• Каждый последующий вызов инструмента MCP имеет доступ к ключу пользователя через this.props.

Это означает, что MCP — это OAuth снаружи (для Claude) и API-ключ внутри (для Twenty).

Области действия (Scoping)

Каждое соединение может быть ограничено во время установки:

• Режим: «только чтение» скрывает create_record / update_record / delete_record.

• Разрешенные объекты: список через запятую для ограничения конкретными объектами.

Права доступа на уровне объектов также принудительно применяются самой системой Twenty через роль, привязанную к API-ключу пользователя — двойная защита.

Архитектура

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.