twenty-crm

Twenty CRM MCP Server exposes a natural language interface for interacting with your Twenty CRM data. It supports CRUD operations across people, companies, tasks, and notes, along with metadata discovery and advanced search. After configuring the server in the Claude Desktop or your MCP client, you can issue conversational prompts like listing people, creating or updating records, and performing cross-object queries. The built-in tools map to dedicated operations (create_person, list_people, create_task, search_records, etc.) so your AI assistant can perform precise actions on your CRM data while staying in sync in real time.

Prerequisites:

• Node.js 18 or higher installed on your host
• Access to a Twenty CRM instance and an API key
• Claude Desktop or another MCP client for integration

Setup steps:

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 from Settings → API & Webhooks (Developers) in your Twenty CRM workspace and keep it handy.
4. Configure Claude Desktop (or your MCP client) to load the MCP server:

• Add a server with:
  • command: node
  • args: ["index.js"]
  • env: TWENTY_API_KEY: your_api_key_here TWENTY_BASE_URL: https://api.twenty.com

5. Restart Claude Desktop to pick up the new server. If you host self-hosted Twenty CRM, set TWENTY_BASE_URL to your domain.

Optional local testing:

• Start the server locally (from project root):

node index.js

• Ensure environment variables are set in your shell or via a .env file (e.g., TWENTY_API_KEY and TWENTY_BASE_URL).

Tips and caveats:

• The server auto-discovers custom fields in Twenty CRM; no extra configuration is needed when you add new fields.
• If you encounter authentication errors, verify that TWENTY_API_KEY is valid and has access to the required CRM data.
• For self-hosted Twenty CRM deployments, ensure TWENTY_BASE_URL points to the correct API endpoint and that any network restrictions allow access.
• When debugging, you can query metadata first (get_metadata_objects) to understand available object types and fields before performing data operations.
• The MCP server supports real-time syncing; changes made through the AI assistant will reflect in Twenty CRM immediately.