Twenty CRM

CI License: MIT Node.js 20.6+

Give Codex, Claude Code, and other MCP clients controlled access to your Twenty CRM.

This is an unofficial, community-built integration. It is not affiliated with, endorsed by, or sponsored by Twenty.com, PBC.

Why this server

Twenty exposes the same operation families across many object types. This server uses a validated entity parameter, so an agent loads 14 composable tools instead of hundreds of near-duplicate tool definitions.

• Read, search, create, update, group, deduplicate, merge, restore, and batch records.
• Covers 28 standard Twenty objects, including companies, people, opportunities, tasks, notes, workflows, calendar objects, and messaging objects.
• Runs locally over stdio. Your API key is sent only to the Twenty API.
• Uses conservative defaults: no hard delete, guarded soft delete and merge, and a restricted write allowlist.
• Returns structured MCP content for reliable follow-up tool calls.

Native Twenty MCP or this server?

Twenty 2.0 introduced native MCP capabilities. If your workspace already provides the access and controls you need, start with the native integration.

This project is useful when you want a small, auditable local stdio process, API-key authentication, compatibility with a self-hosted or older workspace, or explicit safety controls in front of record writes. Its differentiator is a stable 14-tool surface with a write allowlist, dry-run merges, and no hard delete—not replacing every native Twenty feature.

Quick start

1. Requirements

• Node.js 20.6 or newer
• Codex, Claude Code, or another stdio-compatible MCP client
• A Twenty workspace and API key

2. Install

git clone https://github.com/0xfabrica/twentycrm-mcp.git
cd twentycrm-mcp
npm ci
npm test

3. Add your Twenty credentials

Create a local environment file:

cp .env.example .env

Edit .env:

# Twenty Cloud
TWENTY_API_URL=https://api.twenty.com/rest

# Create this in Settings > API & Webhooks
TWENTY_API_KEY=replace_with_your_api_key

# Keep destructive operations disabled for normal agent sessions
TWENTY_ALLOW_DESTRUCTIVE=false

This example omits TWENTY_WRITABLE_ENTITIES, so the server uses its default CRM write allowlist: companies, people, opportunities, tasks, notes, note targets, and task targets. To start in fully read-only mode, add:

TWENTY_WRITABLE_ENTITIES=
TWENTY_ALLOW_DESTRUCTIVE=false

An empty TWENTY_WRITABLE_ENTITIES value disables every write tool. By contrast, TWENTY_ALLOW_DESTRUCTIVE=false only blocks soft deletes and real merges; it does not block ordinary creates, updates, upserts, or restores.

For a self-hosted workspace, use https://your-domain.example/rest. The URL must end in /rest, not /rest/core.

Create the key in Settings > API & Webhooks > Create key. Twenty shows it once, so store it immediately. Assign the key a least-privilege role whenever possible. See the official Twenty API documentation.

The .env file is ignored by Git. On macOS or Linux, you can additionally restrict it to your user:

chmod 600 .env

4. Register the MCP server

Both commands below store absolute paths, so run them from the cloned repo.

Codex

codex mcp add twenty-crm -- node \
  --env-file="$(pwd)/.env" \
  "$(pwd)/dist/index.js"

Inspect the registration:

codex mcp get twenty-crm

For manual configuration, add this to ~/.codex/config.toml and replace both paths:

[mcp_servers.twenty-crm]
command = "node"
args = [
  "--env-file=/absolute/path/to/twentycrm-mcp/.env",
  "/absolute/path/to/twentycrm-mcp/dist/index.js"
]
startup_timeout_sec = 20
tool_timeout_sec = 60
default_tools_approval_mode = "prompt"

Claude Code

claude mcp add --scope user twenty-crm -- node \
  --env-file="$(pwd)/.env" \
  "$(pwd)/dist/index.js"

Inspect the registration:

claude mcp get twenty-crm

Restart the MCP client after registering the server.

Windows PowerShell

From the cloned repository:

$Repo = (Get-Location).Path
Copy-Item .env.example .env
# Edit .env and replace the example API key before continuing.
codex mcp add twenty-crm -- node "--env-file=$Repo\.env" "$Repo\dist\index.js"
claude mcp add --scope user twenty-crm -- node "--env-file=$Repo\.env" "$Repo\dist\index.js"

Then restart Codex or Claude Code and inspect the registration with the same mcp get commands shown above. Codex's manual user configuration is at $env:USERPROFILE\.codex\config.toml.

Do not keep .env in a shared or cloud-synced folder. If you prefer persistent user environment variables on Windows, set them from PowerShell and restart the client:

[Environment]::SetEnvironmentVariable("TWENTY_API_URL", "https://api.twenty.com/rest", "User")
[Environment]::SetEnvironmentVariable("TWENTY_API_KEY", "your-api-key", "User")

Environment-only alternative

If you prefer not to use a local .env, export the variables in the parent environment before launching your MCP client:

export TWENTY_API_URL="https://api.twenty.com/rest"
export TWENTY_API_KEY="your-api-key"

Then register node /absolute/path/to/twentycrm-mcp/dist/index.js without the --env-file argument. Do not place a real key directly in MCP JSON or TOML.

Example prompts

Start with discovery and keep writes explicit:

List the 10 most recently updated companies in Twenty. Do not modify anything.

Find people whose email domain is example.com and summarize their companies.

Preview possible duplicate companies named Acme. Do not merge records.

Create a follow-up task for this opportunity, then show me the created record.

Tools

Safety model

Agents can make mistakes. This server limits the blast radius, but it is not an authorization boundary.

• There is no hard-delete tool.
• Delete operations always request Twenty's soft-delete behavior.
• Soft delete and real merges are disabled unless TWENTY_ALLOW_DESTRUCTIVE=true.
• Merge defaults to dry_run=true.
• Batch creates are limited to 50 records per call.
• Non-local API URLs must use HTTPS.
• API errors do not echo response bodies or credentials.
• Tool annotations tell clients which operations are read-only or destructive.

Use a least-privilege Twenty role, review tool calls before approval, and keep backups appropriate for your workspace.

TWENTY_WRITABLE_ENTITIES: choose what agents may modify

This is a server-side write allowlist. It controls which supported Twenty objects the MCP may create, update, restore, soft-delete, or merge.

If the variable is omitted, writes are allowed by default only for:

companies,people,opportunities,tasks,notes,noteTargets,taskTargets

Set a narrower comma-separated list to reduce write access:

TWENTY_WRITABLE_ENTITIES=companies,people,opportunities,tasks,notes

Set an explicitly empty value for read-only mode:

TWENTY_WRITABLE_ENTITIES=

Objects outside the allowlist remain readable but cannot be modified through this MCP. The allowlist can only reduce access: the role assigned to the Twenty API key must also permit the operation. Keep internal and system objects read-only unless you have reviewed their schema and permissions.

Changes take effect when the MCP process starts. Restart Codex, Claude Code, or your other MCP client after editing .env.

TWENTY_ALLOW_DESTRUCTIVE: guard deletes and merges

Keep this setting false or unset during routine use:

TWENTY_ALLOW_DESTRUCTIVE=false

With false:

• twenty_soft_delete_record and twenty_batch_soft_delete_records are blocked before an HTTP request is sent.
• twenty_merge_records may preview a merge with dry_run=true, but cannot perform the real merge.
• Ordinary creates, upserts, updates, batch writes, and restores are still allowed for objects in TWENTY_WRITABLE_ENTITIES.

Set it to true only for a deliberate, supervised session. The write allowlist and Twenty API-key permissions still apply. This server never exposes a hard delete, even when destructive operations are enabled.

After the supervised operation, set it back to false and restart the MCP client.

Recommended safety presets

Operation risk matrix

TWENTY_ALLOW_DESTRUCTIVE=false does not make the entire server read-only. It blocks soft deletes and real merges; the configured write allowlist still permits ordinary record writes.

An upsert may update an existing record when Twenty finds a matching unique value. Review the proposed data and use a least-privilege API-key role even when destructive operations are disabled.

Configuration reference

Supported objects

The current allowlist contains 28 standard objects:

companies
people
opportunities
tasks
notes
attachments
timelineActivities
dashboards
workflows
workflowVersions
workflowRuns
workflowAutomatedTriggers
calendarEvents
calendarChannels
calendarEventParticipants
calendarChannelEventAssociations
messages
messageChannels
messageThreads
messageParticipants
messageChannelMessageAssociations
messageFolders
messageChannelMessageAssociationMessageFolders
noteTargets
taskTargets
connectedAccounts
blocklists
workspaceMembers

Twenty generates APIs from each workspace schema. Custom objects are not yet accepted by this server's validated entity allowlist; contributions that add a safe discovery mechanism are welcome.

Development and verification

Build the TypeScript server:

npm run build

Run the offline protocol and API-contract smoke test:

npm test

Run the optional live, read-only smoke test after setting credentials:

npm run test:live

The live test lists at most one company and does not modify CRM data. Unlike codex mcp get and claude mcp get, which inspect client registration, this command verifies authenticated access to the Twenty API.

CI runs the build, offline smoke test, and a production-dependency audit on every pull request.

Troubleshooting

TWENTY_API_KEY and TWENTY_API_URL are required

The MCP process cannot see your credentials. Use an absolute .env path in the client configuration or launch the client from a shell that exports both variables.

getaddrinfo ENOTFOUND your-twenty.example.com

The example URL was not replaced. Twenty Cloud uses https://api.twenty.com/rest; self-hosted installations use their own domain.

401 or 403

Replace or rotate the API key, then check the role assigned to that key in Twenty. A valid key can still be denied access to specific objects or writes.

404

Check that the base URL ends in /rest, the entity exists in your workspace, and the record UUID is correct.

The client does not show the tools

Run npm run build, confirm the configured dist/index.js path is absolute, and restart the client. Use codex mcp get twenty-crm or claude mcp get twenty-crm to inspect the registration.

Scope and limitations

• This server targets Twenty's core REST record API, not its metadata API.
• It does not send email. Use an approved Twenty workflow, n8n workflow, or mail integration for delivery.
• Workspace-specific custom objects are not currently auto-discovered.
• Twenty's native MCP may be a better fit for current cloud workspaces.
• Twenty's API and object schemas may change; deploy a reviewed commit or release tag and test it before using sensitive workflows.

Security

Never commit a Twenty API key. If a key appears in a commit, issue, CI log, or terminal transcript, rotate it immediately. See SECURITY.md for the vulnerability-reporting process.

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md and CODE_OF_CONDUCT.md before proposing a change.

License

This project is available under the MIT License.

Twenty is a product and name of Twenty.com, PBC. This independent project uses the name only to identify API compatibility. See NOTICE.md.