🤖 Twenty CRM MCP Server

Transform your CRM into an AI-powered assistant

A Model Context Protocol server that connects Twenty CRM with Claude and other AI assistants, enabling natural language interactions with your customer data.

🚀 Quick Start • 🛠️ Tools • 🔍 Search & Filtering • 🐳 Docker • 🤝 Contributing

---

✨ Features

• Complete CRUD for people, companies, opportunities, notes and tasks
• Working search — built on Twenty's real filter grammar (ilike matching), not the nonexistent search param
• Correct composite-field mapping — flat inputs like firstName/email/amount are converted to Twenty's name/emails/amount composite shapes on write
• Cursor pagination (startingAfter/endingBefore) plus raw filter, orderBy and depth passthrough on every list tool
• Notes & tasks attach to records — pass personId/companyId/opportunityId when creating and the target links are created for you
• Batch creates — up to 60 people or companies per call
• Resilient client — 30s timeouts, automatic retry with backoff on 429/5xx (honors Retry-After), structured error messages
• Schema discovery — metadata tools expose your workspace's objects, fields and enum options, including custom objects

🚀 Installation

Prerequisites

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

Setup

1. Get your Twenty CRM API key: in Twenty, go to Settings → API & Webhooks (under Developers) and generate a key.

2. Configure your MCP client.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "twenty-crm": {
      "command": "npx",
      "args": ["-y", "github:mhenry3164/twenty-crm-mcp-server"],
      "env": {
        "TWENTY_API_KEY": "your_api_key_here",
        "TWENTY_BASE_URL": "https://api.twenty.com"
      }
    }
  }
}

Claude Code:

claude mcp add twenty-crm -e TWENTY_API_KEY=your_api_key_here -e TWENTY_BASE_URL=https://api.twenty.com -- npx -y github:mhenry3164/twenty-crm-mcp-server

Or clone and run from source:

git clone https://github.com/mhenry3164/twenty-crm-mcp-server.git
cd twenty-crm-mcp-server
npm install

then point your client at node /path/to/twenty-crm-mcp-server/index.js.

Environment variables

Variable	Required	Default	Description
TWENTY_API_KEY	✅	—	API key from Settings → API & Webhooks
TWENTY_BASE_URL		https://api.twenty.com	Your instance URL if self-hosted
TWENTY_DEFAULT_CURRENCY		USD	Currency code used when none is given for money fields

💬 Usage

Once configured, use natural language to interact with your Twenty CRM:

"List the first 10 people in my CRM"
"Create a new person named John Doe with email john@example.com at Acme (company id ...)"
"Create a $12,000 opportunity called 'Acme renewal' in PROPOSAL stage"
"Add a note about today's call and attach it to the Acme company record"
"Create a follow-up task due Friday assigned to Sam, linked to the deal"
"Search people, companies and opportunities for 'blockchain'"

🛠️ Tools