Skip to content
Back to search

twenty-crm-mcp-server

A Model Context Protocol (MCP) server for Twenty CRM integration. Enables natural language interactions with your CRM data through Claude and other AI assistants. Supports CRUD operations, dynamic schema discovery, and advanced search across people, companies, tasks, and notes.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mhenry3164--twenty-crm-mcp-server/badge.svg)](/listings/mhenry3164--twenty-crm-mcp-server)

HTML

<a href="/listings/mhenry3164--twenty-crm-mcp-server"><img src="/api/listings/mhenry3164--twenty-crm-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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 |

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 192 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # 🤖 Twenty CRM MCP Server
  3. **Transform your CRM into an AI-powered assistant**
  4. [![CI](https://github.com/mhenry3164/twenty-crm-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/mhenry3164/twenty-crm-mcp-server/actions/workflows/ci.yml)
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  6. [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)
  7. [![Twenty CRM](https://img.shields.io/badge/Twenty_CRM-Compatible-blue)](https://twenty.com)
  8. [![MCP](https://img.shields.io/badge/MCP-Compatible-purple)](https://modelcontextprotocol.io/)
  9. *A Model Context Protocol server that connects [Twenty CRM](https://twenty.com) with Claude and other AI assistants, enabling natural language interactions with your customer data.*
  10. [🚀 Quick Start](#-installation) • [🛠️ Tools](#%EF%B8%8F-tools) • [🔍 Search & Filtering](#-search-filtering--pagination) • [🐳 Docker](#-docker) • [🤝 Contributing](#-contributing)
  11. </div>
  12. ---
  13. ## ✨ Features
  14. - **Complete CRUD** for people, companies, **opportunities**, notes and tasks
  15. - **Working search** — built on Twenty's real `filter` grammar (`ilike` matching), not the nonexistent `search` param
  16. - **Correct composite-field mapping** — flat inputs like `firstName`/`email`/`amount` are converted to Twenty's `name`/`emails`/`amount` composite shapes on write
  17. - **Cursor pagination** (`startingAfter`/`endingBefore`) plus raw `filter`, `orderBy` and `depth` passthrough on every list tool
  18. - **Notes & tasks attach to records** — pass `personId`/`companyId`/`opportunityId` when creating and the target links are created for you
  19. - **Batch creates** — up to 60 people or companies per call
  20. - **Resilient client** — 30s timeouts, automatic retry with backoff on 429/5xx (honors `Retry-After`), structured error messages
  21. - **Schema discovery** — metadata tools expose your workspace's objects, fields and enum options, including custom objects
  22. ## 🚀 Installation
  23. ### Prerequisites
  24. - Node.js 18 or higher
  25. - A Twenty CRM instance (cloud or self-hosted)
  26. - Claude Desktop, Claude Code, or any MCP-compatible client
  27. ### Setup
  28. 1. **Get your Twenty CRM API key**: in Twenty, go to Settings → API & Webhooks (under Developers) and generate a key.
  29. 2. **Configure your MCP client.**
  30. **Claude Desktop** (`claude_desktop_config.json`):
  31. ```json
  32. {
  33. "mcpServers": {
  34. "twenty-crm": {
  35. "command": "npx",
  36. "args": ["-y", "github:mhenry3164/twenty-crm-mcp-server"],
  37. "env": {
  38. "TWENTY_API_KEY": "your_api_key_here",
  39. "TWENTY_BASE_URL": "https://api.twenty.com"
  40. }
  41. }
  42. }
  43. }
  44. ```
  45. **Claude Code**:
  46. ```bash
  47. 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
  48. ```
  49. Or clone and run from source:
  50. ```bash
  51. git clone https://github.com/mhenry3164/twenty-crm-mcp-server.git
  52. cd twenty-crm-mcp-server
  53. npm install
  54. ```
  55. then point your client at `node /path/to/twenty-crm-mcp-server/index.js`.
  56. ### Environment variables
  57. | Variable | Required | Default | Description |
  58. |---|---|---|---|
  59. | `TWENTY_API_KEY` | ✅ | — | API key from Settings → API & Webhooks |
  60. | `TWENTY_BASE_URL` | | `https://api.twenty.com` | Your instance URL if self-hosted |
  61. | `TWENTY_DEFAULT_CURRENCY` | | `USD` | Currency code used when none is given for money fields |
  62. ## 💬 Usage
  63. Once configured, use natural language to interact with your Twenty CRM:
  64. ```
  65. "List the first 10 people in my CRM"
  66. "Create a new person named John Doe with email john@example.com at Acme (company id ...)"
  67. "Create a $12,000 opportunity called 'Acme renewal' in PROPOSAL stage"
  68. "Add a note about today's call and attach it to the Acme company record"
  69. "Create a follow-up task due Friday assigned to Sam, linked to the deal"
  70. "Search people, companies and opportunities for 'blockchain'"
  71. ```
  72. ## 🛠️ Tools
  73. | Category | Tools |
  74. |---|---|
  75. | **People** | `create_person`, `get_person`, `update_person`, `list_people`, `delete_person` |
  76. | **Companies** | `create_company`, `get_company`, `update_company`, `list_companies`, `delete_company` |
  77. | **Opportunities** | `create_opportunity`, `get_opportunity`, `update_opportunity`, `list_opportunities`, `delete_opportunity` |
  78. | **Notes** | `create_note` (with record targets), `get_note`, `update_note`, `list_notes`, `delete_note` |
  79. | **Tasks** | `create_task` (with record targets + assignee), `get_task`, `update_task`, `list_tasks`, `delete_task` |
  80. | **Batch** | `batch_create_people`, `batch_create_companies` (up to 60 records) |
  81. | **Workspace** | `list_workspace_members` (for task assignment) |
  82. | **Metadata** | `get_metadata_objects`, `get_object_metadata` |
  83. | **Search** | `search_records` (across people, companies, opportunities, notes, tasks) |
  84. ### Composite fields, handled for you
  85. Twenty stores identity/contact/money data in composite fields. This server accepts flat parameters and maps them to the shapes the API expects:
  86. | You pass | Twenty receives |
  87. |---|---|
  88. | `firstName`, `lastName` | `name: { firstName, lastName }` |
  89. | `email` | `emails: { primaryEmail, additionalEmails: [] }` |
  90. | `phone` | `phones: { primaryPhoneNumber, ... }` |
  91. | `linkedinUrl` / `xUrl` / `domainName` | `{ primaryLinkUrl, ... }` link composites |
  92. | `amount: 12000` + `currencyCode` | `amount: { amountMicros: 12000000000, currencyCode }` |
  93. | `body` (notes/tasks) | `bodyV2: { markdown }` |
  94. | `address` (string) | `address: { addressStreet1, ... }` (or pass a full address object) |
  95. Anything else — including your workspace's custom fields — passes through untouched.
  96. > **Note on company revenue:** the field is `annualRecurringRevenue` on most deployed Twenty versions and `annualRevenue` on Twenty v2.x+. Both parameters are supported; use the one that matches your instance (check `get_object_metadata` for `companies` if unsure).
  97. ## 🔍 Search, filtering & pagination
  98. Twenty's REST API has no `search` or `offset` query params — this server builds real filters instead:
  99. - **`search`** on list tools becomes a case-insensitive `ilike` filter across sensible fields per object (people: first/last name + email; companies: name + domain; opportunities/notes/tasks: name/title).
  100. - **`filter`** accepts Twenty's raw filter grammar for anything more specific:
  101. - `createdAt[gte]:2026-01-01`
  102. - `or(city[eq]:Austin,city[eq]:Dallas)`
  103. - `emails.primaryEmail[ilike]:%@acme.com`
  104. - Comparators: `eq, neq, in, containsAny, is, gt, gte, lt, lte, startsWith, endsWith, like, ilike`; combine with `and(...)`, `or(...)`, `not(...)`. Use `field[is]:NULL` / `NOT_NULL` for empty checks.
  105. - **`orderBy`**: e.g. `createdAt[DescNullsLast]` (directions: `AscNullsFirst`, `AscNullsLast`, `DescNullsFirst`, `DescNullsLast`).
  106. - **Pagination is cursor-based**: results include `pageInfo.endCursor` — pass it as `startingAfter` for the next page. `limit` max is 200.
  107. - **`depth`**: `0` (default) or `1` to include first-level related records.
  108. ## 🐳 Docker
  109. ```bash
  110. docker build -t twenty-crm-mcp-server .
  111. ```
  112. ```json
  113. {
  114. "mcpServers": {
  115. "twenty-crm": {
  116. "command": "docker",
  117. "args": ["run", "-i", "--rm", "-e", "TWENTY_API_KEY", "-e", "TWENTY_BASE_URL", "twenty-crm-mcp-server"],
  118. "env": {
  119. "TWENTY_API_KEY": "your_api_key_here",
  120. "TWENTY_BASE_URL": "https://api.twenty.com"
  121. }
  122. }
  123. }
  124. }
  125. ```
  126. ## 🧪 Development
  127. ```bash
  128. npm install
  129. npm test # unit tests (node --test, no network needed)
  130. npm start # run the stdio server
  131. ```
  132. ## ⬆️ Upgrading from v1.x
  133. v2.0.0 fixes writes and search against the actual Twenty API. Breaking changes:
  134. - `offset` was removed from list tools (Twenty's REST API never supported it) — use cursor pagination (`startingAfter`).
  135. - Note/task `body` now maps to `bodyV2.markdown`; `position` params were dropped.
  136. - Updates now use `PATCH` (Twenty's documented verb) instead of `PUT`.
  137. - List results are returned as `{ records, pageInfo, totalCount? }` instead of the raw API envelope.
  138. ## 🤝 Contributing
  139. This project is **community-supported** — the maintainer no longer runs Twenty day-to-day, so bug reports and PRs from active Twenty users are especially welcome and get reviewed and merged. See [CONTRIBUTING.md](CONTRIBUTING.md).
  140. v2.0.0 builds on excellent community work: composite-field mapping ([#4](https://github.com/mhenry3164/twenty-crm-mcp-server/pull/4) by @zaks), filter-based search ([#6](https://github.com/mhenry3164/twenty-crm-mcp-server/pull/6) by @studio7A, [#8](https://github.com/mhenry3164/twenty-crm-mcp-server/pull/8) by @InDebted-Growth), opportunity tools ([#7](https://github.com/mhenry3164/twenty-crm-mcp-server/pull/7) by @tarikhennen), and patterns from the forks by @BCJonkhout, @archie1492, @ndrkltsk and @atilladeniz.
  141. ## 📄 License
  142. MIT — see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.