Twenty MCP

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

Что он делает

Предоставляет 9 универсальных инструментов, управляемых схемой, которые работают с любым объектом 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)

Related MCP server: twentycrm-graphql-mcp

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

1. В Claude → Settings → Connectors → Add custom connector

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

3. Claude перенаправит вас на страницу согласия, где вам понадобится ваш личный API-ключ Twenty. Чтобы получить его:

   • Войдите в свое рабочее пространство Twenty в браузере

   • Нажмите на значок шестеренки (внизу слева) → Settings

   • Перейдите в Developers (в разделе Workspace на боковой панели)

   • Нажмите + Create API key, дайте ему имя (например, "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

Ваш URL Worker будет https://hia-twenty-mcp.<your-subdomain>.workers.dev. Поделитесь <url>/mcp с командой.

Для команд, управляемых Claude: зарегистрируйте <url>/mcp один раз в консоли администратора команды Claude — он появится в списке коннекторов каждого члена команды. Каждый участник все равно проходит однократную страницу согласия, чтобы вставить свой собственный API-ключ Twenty.

Дополнительно: установка токена администратора

Включает конечные точки /admin/* для загрузки контекста primer, специфичного для организации (см. Настройка primer):

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

Настройка primer

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

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

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

Контекст в формате 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

# 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 к рабочему экземпляру (dev worker), добавьте http://localhost:8787/mcp в качестве коннектора.

Как работает аутентификация

У Twenty нет вышестоящего провайдера OAuth — аутентификация осуществляется через API-ключи для каждого рабочего пространства. Поэтому:

• Worker запускает свою собственную конечную точку OAuth 2.1 (требуется коннекторами Claude).

• Во время шага согласия OAuth пользователь вставляет свой API-ключ Twenty в HTML-форму.

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

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

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

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

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

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

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

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

Совместимость с версиями Twenty

Протестировано с Twenty v0.40+. MCP использует:

• REST API (/rest/<objects>) для CRUD записей — глубина ограничена 0 или 1

• GraphQL metadata API (/metadata) для интроспекции схемы — использует поле settings в типе Field для информации о связях

• Составные поля (например, name.firstName, emails.primaryEmail) должны быть записаны через точку в фильтрах

Если вы используете значительно более старую версию Twenty, форма запроса метаданных может отличаться. Откройте issue, если столкнетесь с ошибками.

Архитектура

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