twency-crm-mcp

Model Context Protocol (MCP) server for Twenty CRM workspaces.

It provides a practical admin and operations layer for:

• records CRUD across any object,
• metadata object and field management,
• schema-as-code export, diff, and apply,
• workflow read, validation, create, update, activate, and deactivate.

Why this project

Many Twenty integrations expose basic CRUD but stop short of safe metadata and workflow administration. twency-crm-mcp is built to support real operational work from AI tools: evolving schema, linking relations, and managing workflow definitions with consistent error handling.

Features

• Generic records tools for all objects (records_*)
• Metadata tools for custom objects/fields/relations (meta_*)
• Batch tools (records_upsert_batch, meta_create_fields_batch)
• Schema-as-code tools (schema_export, schema_diff, schema_apply)
• Workflow tools (workflow_*) with definition validation and sync helpers
• Auto-retry for transient API failures (429/502/503/504)
• Normalized error contract across tools
• Auto-renewed user session auth (email/password)
• Optional fallback to bearer token and/or API key

Requirements

• Node.js 18+
• Twenty workspace base URL (self-hosted or cloud)
• One auth mode:
  • recommended: user session (TWENTY_AUTH_EMAIL + TWENTY_AUTH_PASSWORD)
  • optional: bearer token (TWENTY_AUTH_BEARER_TOKEN)
  • optional: API key (TWENTY_API_KEY)

Install

Global install:

npm i -g @neutralthiscrazy/twency-crm-mcp

Or use directly with npx:

npx -y @neutralthiscrazy/twency-crm-mcp

Authentication modes

Auth priority order:

1. auto user session (TWENTY_AUTH_EMAIL + TWENTY_AUTH_PASSWORD)
2. bootstrap bearer token (TWENTY_AUTH_BEARER_TOKEN)
3. API key (TWENTY_API_KEY)

Service account recommendation

For production, use a dedicated service account (for example, mcp-bot) for MCP automation.

• Do not use a personal owner/admin account for long-lived automation.
• Grant only the permissions required by enabled tool groups:
  • records tools: object read/write operations
  • metadata tools: object/field administration
  • workflow tools: workflow and workflow-version mutations
• Store credentials in a secrets manager.
• Rotate service-account credentials on a schedule.
• Use TWENTY_AUTH_STRICT_USER_AUTH=true to avoid silent fallback to weaker auth scope.

Deployment compatibility

• The server is tested primarily against a self-hosted Twenty deployment.
• It can also work with cloud-hosted Twenty workspaces when the same REST and GraphQL endpoints are available to your credentials.
• If your workspace adds auth gateways (SSO-only, captcha, proxy restrictions), you may need to adapt auth settings or network headers.

With user session enabled, the server:

1. calls getLoginTokenFromCredentials,
2. exchanges via getAuthTokensFromLoginToken,
3. uses access token for requests,
4. renews via renewToken,
5. relogs if renewal fails.

Set TWENTY_AUTH_STRICT_USER_AUTH=true to prevent silent fallback to API key scope.

Environment variables

See env.sample.

Minimal recommended setup:

TWENTY_BASE_URL="https://crm.example.com"
TWENTY_AUTH_EMAIL="admin@example.com"
TWENTY_AUTH_PASSWORD="replace_me"
TWENTY_AUTH_ORIGIN="https://crm.example.com"
TWENTY_AUTH_STRICT_USER_AUTH="true"

MCP client configuration

Example ~/.config/opencode/opencode.json block:

{
  "mcp": {
    "twency-crm": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@neutralthiscrazy/twency-crm-mcp"
      ],
      "enabled": true,
      "environment": {
        "TWENTY_BASE_URL": "https://crm.example.com",
        "TWENTY_AUTH_EMAIL": "admin@example.com",
        "TWENTY_AUTH_PASSWORD": "replace_me",
        "TWENTY_AUTH_ORIGIN": "https://crm.example.com",
        "TWENTY_AUTH_REFRESH_SKEW_SEC": "120",
        "TWENTY_AUTH_STRICT_USER_AUTH": "true",
        "TWENTY_TIMEOUT_MS": "30000",
        "TWENTY_RETRY_MAX_ATTEMPTS": "4",
        "TWENTY_RETRY_BASE_DELAY_MS": "500",
        "TWENTY_RETRY_MAX_DELAY_MS": "8000",
        "TWENTY_RETRY_JITTER_RATIO": "0.25"
      }
    }
  }
}

Tool groups

Records

• records_list
• records_get
• records_create
• records_update
• records_delete
• records_upsert_batch

Metadata

• meta_list_objects
• meta_get_object
• meta_get_field
• meta_icon_catalog
• meta_find_dependencies
• meta_create_object
• meta_update_object
• meta_set_object_active
• meta_delete_object
• meta_create_field
• meta_create_fields_batch
• meta_update_field
• meta_set_field_active
• meta_delete_field

Schema-as-code

• schema_export
• schema_diff
• schema_apply

Workflows

• workflow_get
• workflow_validate_definition
• workflow_create_from_definition
• workflow_update_from_definition
• workflow_activate_version
• workflow_deactivate_version

Escape hatch

• graphql_query

Workflow scope notes

• User-session auth is strongly recommended for workflow mutations.
• API key auth may be insufficient for step-level operations in some workspaces.
• Automated trigger sync handles known Twenty payload inconsistency (workflow vs workflowId) and returns explicit skip details when Twenty rejects all variants.

Safety and error model

• Destructive delete tools require confirm: "DELETE".
• Schema apply execution requires confirm: "APPLY" when dryRun=false.
• Errors are normalized to:
  • error
  • category
  • code
  • status
  • retryable
  • details

Local development

git clone https://github.com/Neutralthiscrazy/twency-crm-mcp.git
cd twency-crm-mcp
npm install
npm run check

Run locally:

TWENTY_BASE_URL="https://crm.example.com" \
TWENTY_AUTH_EMAIL="admin@example.com" \
TWENTY_AUTH_PASSWORD="replace_me" \
TWENTY_AUTH_STRICT_USER_AUTH="true" \
node src/index.js

Security

• Never commit real credentials, tokens, or workspace-specific secrets.
• Use placeholders in config examples.
• For disclosure process, see SECURITY.md.

Documentation

• Architecture
• Authentication
• Workflow behavior
• Development guide
• Deployment guide
• API implementation notes

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request.

License

MIT - see LICENSE.