Twenty CRM

This MCP server lets you connect Twenty CRM to Claude and other AI assistants, enabling natural language interactions with your customer data. You can manage people, companies, tasks, and notes directly from conversational prompts, with real-time syncing and automatic discovery of custom fields.

How to use

You interact with Twenty CRM through an MCP client. Ask natural language questions or give commands to create, read, update, or delete CRM records. The server exposes a set of capabilities that cover people, companies, tasks, notes, and metadata search, so you can perform complex queries across multiple object types in a single conversation.

How to install

Prerequisites you need before you start:

node -v
npm -v

# Node.js 18+ and npm are required
# Verify you have them installed
node -v
npm -v

Follow these steps to install and run the MCP server locally:

# 1. Clone the repository
git clone https://github.com/mhenry3164/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
# Navigate to Settings → API & Webhooks (under Developers)
# Generate a new API key

# 4. Configure Claude Desktop
# Open claude_desktop_config.json and add the MCP server entry shown below

{
  "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"
      }
    }
  }
}

5. Restart Claude Desktop to load the new server. If you are using a self-hosted Twenty instance, set TWENTY_BASE_URL to your domain.

Configuration

Environment variables you need to configure for the MCP server are:

• TWENTY_API_KEY: Your Twenty CRM API key (required)
• TWENTY_BASE_URL: Base URL for the Twenty CRM API (defaults to https://api.twenty.com)

The server automatically discovers and supports custom fields in your Twenty CRM instance. No extra configuration is needed when you add new fields.

Troubleshooting

Common issues and solutions:

• Authentication Error: Ensure your API key is correct and has the necessary permissions.
• Connection Failed: Verify TWENTY_BASE_URL is correct, especially for self-hosted instances.
• Field Not Found: The server discovers fields automatically. If you encounter this, fetch metadata first to see available fields.

Notes

From conversational prompts, you can perform CRUD operations across people, companies, tasks, and notes, perform advanced searches, and retrieve metadata about schemas and fields. All changes sync in real time with Twenty CRM.

Available tools

create_person

Create a new person in Twenty CRM with specified attributes like name and email.

get_person

Retrieve details for a person by ID.

update_person

Update person details such as name, email, or custom fields.

list_people

List people with filtering options and pagination.

delete_person

Remove a person from Twenty CRM.

create_company

Create a new company with given attributes.

get_company

Get details for a company by ID.

update_company

Update company information and fields.

list_companies

List companies with filtering and sorting.

delete_company

Delete a company record.

create_task

Create a new task assigned to a person or company.

get_task

Fetch task details by ID.

update_task

Update task properties like status or due date.

list_tasks

List tasks with filters such as overdue or completed.

delete_task

Delete a task.

create_note

Create a note related to a CRM record.

get_note

Retrieve a note by ID.

update_note

Update note content.

list_notes

List notes with optional filters.

delete_note

Delete a note.

get_metadata_objects

Retrieve all object types and their schemas.

get_object_metadata

Get metadata for a specific object type.

search_records

Search across multiple object types using keywords and filters.