Twenty Crm Mcp Server

🤖 Twenty CRM MCP Server

Connect Twenty CRM with Claude and AI Assistants via Model Context Protocol

[](https://opensource.org/licenses/MIT) [](https://nodejs.org/) [](https://twenty.com) [](https://modelcontextprotocol.io/)

Manage your CRM data using natural language through Claude, with full support for Twenty's composite fields and GraphQL API.

[Features](#-features) • [Installation](#-installation) • [Usage](#-usage) • [API Reference](#-api-reference) • [Contributing](#-contributing)

---

✨ Features

• 🚀 GraphQL-Native - Built on Twenty's GraphQL API for robust, type-safe operations
• 🔄 Full CRUD Support - Create, read, update, and list people, companies, opportunities, tasks, and notes
• 🏗️ Composite Fields - Proper handling of nested objects (name, emails, phones, addresses, links)
• 💰 Currency Support - Automatic conversion for deal amounts and Annual Recurring Revenue
• 🔍 Smart Search - Filter and search across all CRM objects
• 📊 Sales Pipeline - Track opportunities with stages, amounts, and close dates
• ✅ Task Management - Create, assign, and track tasks with statuses and due dates
• 📝 Note Operations - Add and manage notes with rich text support
• 🔗 Relationship Linking - Link tasks and notes to people, companies, and opportunities
• 📅 Timeline Activities - Track all interactions, events, and changes with full history
• ⭐ Favorites Management - Quick access to frequently used records
• 📎 Attachment Support - Upload and manage files linked to any CRM record
• ⚡ Real-time Updates - Changes sync immediately with your Twenty instance
• 🛡️ Type-Safe - Full TypeScript implementation with comprehensive type definitions
• 🧪 Tested - Comprehensive unit tests with 86+ test cases
• 📖 Well-Documented - Comprehensive guides and examples

🎯 What You Can Do

Manage People:

"Create a contact named Sarah Johnson, email sarah@techco.com, phone +1-555-0100"
"Find all people working at TechCo"
"Update John's job title to Senior Developer"
"List the first 10 contacts in the database"

Manage Companies:

"Add a company called Acme Corp with website acme.com, 50 employees, and ARR of $2M"
"Show me all companies in San Francisco"
"Update TechStartup's address to 123 Main St, Berlin, Germany"
"List all ideal customer profile companies"

Manage Opportunities:

"Create an opportunity called 'Enterprise Deal' for Acme Corp worth €50,000 closing on Dec 31st"
"Show me all opportunities in the MEETING stage"
"Update the Enterprise Deal to PROPOSAL stage with amount €75,000"
"List all opportunities for TechCo"

Manage Tasks:

"Create a task to follow up with Sarah next week with status TODO"
"Show me all IN_PROGRESS tasks"
"Update task to DONE status"
"List all tasks assigned to user-123"

Manage Notes:

"Create a note titled 'Meeting Summary' with the key discussion points"
"Show me the note with ID note-456"
"Update the meeting notes with additional information"
"List all notes about the Enterprise Deal"

Link Tasks & Notes to Records:

"Link task task-123 to person Sarah Johnson"
"Show all tasks linked to Acme Corp"
"Link this note to the Enterprise Deal opportunity"
"Remove the link between task and company"

Track Timeline Activities:

"Create a timeline activity for a call with TechCo"
"Log a meeting event for next Tuesday with Acme Corp"
"Show all timeline activities for Sarah Johnson"
"Update the timeline activity with meeting notes"

Manage Favorites:

"Add Acme Corp to my favorites"
"Show all my favorited companies"
"Add Sarah Johnson to favorites"
"Remove TechCo from favorites"

Manage Attachments:

"Attach the project proposal PDF to task task-123"
"Upload company-logo.png and link it to Acme Corp"
"Show all attachments for the Enterprise Deal opportunity"
"List all IMAGE attachments"
"Find attachments with 'contract' in the name"
"Delete attachment att-456"

🚀 Installation

Prerequisites

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

Option 1: Install via npm (Recommended)

The easiest way to use this server is via npx:

1. Get your Twenty CRM API key:

• Log in to your Twenty CRM instance
• Navigate to Settings → API & Webhooks (under Developers)
• Click Generate API Key
• Copy the key

1. Configure Claude Desktop:

Edit your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

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

For self-hosted Twenty: ``json "TWENTY_BASE_URL": "https://your-twenty-instance.com" ``

1. Restart Claude Desktop

Option 2: Install from Source

1. Clone the repository:

``bash git clone https://github.com/KonstiDoll/twenty-crm-mcp-server.git cd twenty-crm-mcp-server ``

1. Install dependencies:

``bash npm install ``

1. Build the project:

``bash npm run build ``

1. Get your Twenty CRM API key:

• Log in to your Twenty CRM instance
• Navigate to Settings → API & Webhooks (under Developers)
• Click Generate API Key
• Copy the key

1. Configure Claude Desktop:

Edit your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

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

For self-hosted Twenty: ``json "TWENTY_BASE_URL": "https://your-twenty-instance.com" ``

1. Restart Claude Desktop

💬 Usage

Once configured, interact with your CRM using natural language:

Creating Records

People:

"Create a person named Max Mustermann with email max@example.com,
phone +49-123-456789, works at Acme Corp as Software Engineer in Berlin,
LinkedIn: linkedin.com/in/maxmustermann"

Companies:

"Create a company called TechStartup GmbH with:
- Website: techstartup.io
- Address: Hauptstraße 123, 10115 Berlin, Germany
- 25 employees
- ARR: €500,000
- Mark as ideal customer profile
- LinkedIn: linkedin.com/company/techstartup"

Opportunities:

"Create an opportunity named 'Q4 Enterprise Deal' for TechStartup:
- Amount: €100,000
- Stage: NEW
- Close date: 2025-12-31
- Point of contact: Max Mustermann"

Querying Data

"Show me all people in the CRM"
"List companies with more than 100 employees"
"Find all contacts at Acme Corp"
"Search for people with 'smith' in their name"
"Show all opportunities in MEETING stage"
"List opportunities for TechStartup"

Updating Records

"Update Sarah's job title to VP of Engineering"
"Change Acme Corp's employee count to 75"
"Update TechStartup's address city to Munich"
"Move the Enterprise Deal to PROPOSAL stage"
"Update Q4 Enterprise Deal amount to €150,000"

🛠️ API Reference

Person Operations

| Tool | Description | Required Fields | |------|-------------|----------------| | create_person | Create a new contact | firstName, lastName | | get_person | Get person by ID | id | | list_people | List/search people | - | | update_person | Update person info | id |

Optional Person Fields:

• email - Primary email address
• phone, phoneCountryCode, phoneCallingCode - Phone details
• jobTitle - Job title
• city - City
• companyId - Link to company
• linkedinUrl, xUrl - Social profiles

Company Operations

| Tool | Description | Required Fields | |------|-------------|----------------| | create_company | Create a new company | name | | get_company | Get company by ID | id | | list_companies | List/search companies | - | | update_company | Update company info | id |

Optional Company Fields:

• domainUrl - Company website
• addressStreet1, addressStreet2, addressCity, addressPostcode, addressState, addressCountry - Full address
• employees - Number of employees
• annualRecurringRevenue, currency - ARR (auto-converted to micros)
• linkedinUrl, xUrl - Social profiles
• idealCustomerProfile - Boolean flag

Opportunity Operations

| Tool | Description | Required Fields | |------|-------------|----------------| | create_opportunity | Create a new opportunity | name | | get_opportunity | Get opportunity by ID | id | | list_opportunities | List/search opportunities | - | | update_opportunity | Update opportunity info | id |

Optional Opportunity Fields:

• amount, currency - Deal amount (auto-converted to micros)
• stage - Opportunity stage (e.g., 'NEW', 'SCREENING', 'MEETING', 'PROPOSAL', 'CUSTOMER')
• closeDate - Expected close date (ISO 8601 format: YYYY-MM-DD)
• companyId - Link to company
• pointOfContactId - Link to person (point of contact)

List Opportunities Filters:

• limit - Number of results (max: 60, default: 20)
• searchTerm - Search by opportunity name
• companyId - Filter by company
• stage - Filter by stage

Task Operations

| Tool | Description | Required Fields | |------|-------------|----------------| | create_task | Create a new task | title | | get_task | Get task by ID | id | | list_tasks | List/search tasks | - | | update_task | Update task info | id |

Optional Task Fields:

• body - Task description/body in markdown format
• status - Task status: 'TODO', 'IN_PROGRESS', 'DONE' (default: 'TODO')
• dueAt - Due date (ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ)
• assigneeId - ID of the workspace member to assign the task to
• personId - Auto-link task to person (creates task target automatically)
• companyId - Auto-link task to company (creates task target automatically)
• opportunityId - Auto-link task to opportunity (creates task target automatically)

List Tasks Filters:

• limit - Number of results (max: 60, default: 20)
• searchTerm - Search by task title
• status - Filter by status ('TODO', 'IN_PROGRESS', 'DONE')
• assigneeId - Filter by assignee

Note Operations

| Tool | Description | Required Fields | |------|-------------|----------------| | create_note | Create a new note | title | | get_note | Get note by ID | id | | list_notes | List/search notes | - | | update_note | Update note info | id | | delete_note | Delete a note | id |

Optional Note Fields:

• body - Note body/content in markdown format
• personId - Auto-link note to person (creates note target automatically)
• companyId - Auto-link note to company (creates note target automatically)
• opportunityId - Auto-link note to opportunity (creates note target automatically)

List Notes Filters:

• limit - Number of results (max: 60, default: 20)
• searchTerm - Search by note title

TaskTarget Operations

| Tool | Description | Required Fields | |------|-------------|----------------| | create_task_target | Link a task to a person/company/opportunity | taskId | | list_task_targets | List task-record links | - | | delete_task_target | Remove task-record link | id |

TaskTarget Fields:

• taskId - Task ID to link (required)
• personId - Person ID to link the task to
• companyId - Company ID to link the task to
• opportunityId - Opportunity ID to link the task to

Note: At least one target (personId, companyId, or opportunityId) must be provided.

List TaskTargets Filters:

• taskId - Filter by task ID (show all entities linked to this task)
• personId - Filter by person ID (show all tasks linked to this person)
• companyId - Filter by company ID (show all tasks linked to this company)
• opportunityId - Filter by opportunity ID (show all tasks linked to this opportunity)
• limit - Number of results (max: 60, default: 20)

NoteTarget Operations

| Tool | Description | Required Fields | |------|-------------|----------------| | create_note_target | Link a note to a person/company/opportunity | noteId | | list_note_targets | List note-record links | - | | delete_note_target | Remove note-record link | id |

NoteTarget Fields:

• noteId - Note ID to link (required)
• personId - Person ID to link the note to
• companyId - Company ID to link the note to
• opportunityId - Opportunity ID to link the note to

Note: At least one target (personId, companyId, or opportunityId) must be provided.

List NoteTargets Filters:

• noteId - Filter by note ID (show all entities linked to this note)
• personId - Filter by person ID (show all notes linked to this person)
• companyId - Filter by company ID (show all notes linked to this company)
• opportunityId - Filter by opportunity ID (show all notes linked to this opportunity)
• limit - Number of results (max: 60, default: 20)

Timeline Activity Operations

| Tool | Description | Required Fields | |------|-------------|----------------| | create_timeline_activity | Create a timeline activity event | name | | get_timeline_activity | Get timeline activity by ID | id | | list_timeline_activities | List/search timeline activities | - | | update_timeline_activity | Update timeline activity info | id |

Timeline Activity Fields:

• name - Activity name/title (required)
• properties - JSON object with activity details (e.g., {type: 'CALL', notes: 'Discussed pricing'})
• happensAt - When the activity occurred (ISO 8601 format)
• workspaceMemberId - ID of the workspace member associated with this activity
• personId - Person ID to associate with this activity
• companyId - Company ID to associate with this activity
• opportunityId - Opportunity ID to associate with this activity
• noteId - Note ID to associate with this activity
• taskId - Task ID to associate with this activity
• linkedRecordId - Linked record ID
• linkedObjectMetadataId - Linked object metadata ID
• linkedRecordCachedName - Cached name of the linked record

List Timeline Activities Filters:

• limit - Number of results (max: 60, default: 20)
• searchTerm - Search by activity name
• personId - Filter by person ID
• companyId - Filter by company ID
• opportunityId - Filter by opportunity ID
• workspaceMemberId - Filter by workspace member ID
• noteId - Filter by note ID
• taskId - Filter by task ID

Favorite Operations

| Tool | Description | Required Fields | |------|-------------|----------------| | add_favorite | Add a record to favorites | - | | get_favorite | Get favorite by ID | id | | list_favorites | List all favorites | - | | remove_favorite | Remove a record from favorites | id |

Favorite Fields:

• personId - Person ID to add to favorites
• companyId - Company ID to add to favorites
• opportunityId - Opportunity ID to add to favorites
• position - Position in favorites list (optional)

Note: At least one target (personId, companyId, or opportunityId) must be provided for add_favorite.

List Favorites Filters:

• limit - Number of results (max: 60, default: 20)
• personId - Filter by person ID
• companyId - Filter by company ID
• opportunityId - Filter by opportunity ID
• workspaceMemberId - Filter by workspace member ID

Attachment Operations

| Tool | Description | Required Fields | |------|-------------|--------------

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: KonstiDoll
• Source: KonstiDoll/twenty-crm-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.