Twenty CRM MCP Server

A Model Context Protocol (MCP) server that connects Twenty CRM with Claude and other AI assistants, so you can manage your CRM data with natural language.

Repository: https://github.com/SaschaRoelofs/twenty-crm-mcp-server

Features

• Full CRUD for people, companies, opportunities, tasks, and notes
• Generic record tools (list_records, get_record, create_record, update_record, delete_record) that work with any standard or custom object — including ones added after this server was written
• Dynamic schema discovery — automatically adapts to your Twenty CRM configuration and custom fields
• Search across multiple object types
• Workflow triggering for workflows with a webhook trigger

Installation

Prerequisites

• Node.js 18 or higher
• A Twenty CRM instance (cloud or self-hosted)
• Claude Desktop or another MCP-compatible client

Setup

1. Clone the repository:

   git clone https://github.com/SaschaRoelofs/twenty-crm-mcp-server.git
   cd twenty-crm-mcp-server
   

2. Install dependencies:

   npm install
   

3. Get your Twenty CRM API key:

   • Log in to your Twenty CRM workspace
   • Go to Settings → API & Webhooks (under Developers)
   • Generate a new API key

4. Add the server to your claude_desktop_config.json:

   {
     "mcpServers": {
       "twenty-crm": {
         "command": "node",
         "args": ["/path/to/twenty-crm-mcp-server/index.js"],
         "env": {
           "TWENTY_API_KEY": "your_api_key_here",
           "TWENTY_BASE_URL": "https://api.twenty.com"
         }
       }
     }
   }
   

   For self-hosted Twenty instances, change TWENTY_BASE_URL to your own domain.

5. Restart Claude Desktop to load the server.

Usage

Once configured, just talk to Claude naturally:

"List the first 10 people in my CRM"
"Create a new person named John Doe with email john@example.com"
"Show me all companies with more than 100 employees"
"Create a $10,000 opportunity called 'Acme Renewal' for Acme Corp"
"Create a task to follow up with John next Friday"
"Add a note about my meeting with the client today"
"Search for any records mentioning 'blockchain'"
"Trigger the 'Send Welcome Email' workflow for this contact"

API Reference

<details> <summary><strong>People</strong></summary>

• create_person, get_person, update_person, list_people, delete_person

</details>

<details> <summary><strong>Companies</strong></summary>

• create_company, get_company, update_company, list_companies, delete_company

</details>

<details> <summary><strong>Opportunities</strong></summary>

• create_opportunity, get_opportunity, update_opportunity, list_opportunities, delete_opportunity

</details>

<details> <summary><strong>Tasks</strong></summary>

• create_task, get_task, update_task, list_tasks, delete_task

</details>

<details> <summary><strong>Notes</strong></summary>

• create_note, get_note, update_note, list_notes, delete_note
• link_note / unlink_note — link or unlink a note to a person, company, or opportunity
• list_note_targets — list note-to-record links, optionally filtered

</details>

<details> <summary><strong>Metadata & search</strong></summary>

• get_metadata_objects - Get all object types and schemas
• get_object_metadata - Get metadata for a specific object
• search_records - Search across multiple object types

</details>

<details> <summary><strong>Generic record operations (any object type)</strong></summary>

These work with any standard or custom object type by its plural API name (e.g. people, opportunities, or a custom object like projects), so the server keeps working even if objects or fields change in your workspace. Use get_metadata_objects / get_object_metadata to discover valid object type names and fields.

• list_records, get_record, create_record, update_record, delete_record

</details>

<details> <summary><strong>Workflows</strong></summary>

Workflows are standard Twenty objects, so you can already browse them with the generic tools above: list_records/get_record with objectType set to workflows, workflowVersions, or workflowRuns.

• trigger_workflow - Trigger a run of a workflow that has a Webhook trigger configured in the Twenty UI (Workflows → your workflow → Trigger → Webhook). Requires the workflow ID and a workspace ID (from TWENTY_WORKSPACE_ID or passed per-call).

</details>

Configuration

Variable	Required	Description
TWENTY_API_KEY	Yes	Your Twenty CRM API key
TWENTY_BASE_URL	No	Twenty CRM base URL (defaults to https://api.twenty.com)
TWENTY_WORKSPACE_ID	No	Workspace ID, needed only for trigger_workflow. Can also be passed per-call as workspaceId.

Custom fields are discovered automatically — no configuration changes needed when you add new fields in Twenty.

Development

git clone https://github.com/SaschaRoelofs/twenty-crm-mcp-server.git
cd twenty-crm-mcp-server
npm install
cp .env.example .env   # add your API key
npm test

License

MIT