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.
Badge for your README
Markdown
[](/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
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)
- <div align="center">
- # 🤖 Twenty CRM MCP Server
- **Transform your CRM into an AI-powered assistant**
- [](https://github.com/mhenry3164/twenty-crm-mcp-server/actions/workflows/ci.yml)
- [](https://opensource.org/licenses/MIT)
- [](https://nodejs.org/)
- [](https://twenty.com)
- [](https://modelcontextprotocol.io/)
- *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.*
- [🚀 Quick Start](#-installation) • [🛠️ Tools](#%EF%B8%8F-tools) • [🔍 Search & Filtering](#-search-filtering--pagination) • [🐳 Docker](#-docker) • [🤝 Contributing](#-contributing)
- </div>
- ---
- ## ✨ 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`):
- ```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**:
- ```bash
- 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:
- ```bash
- 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
- | Category | Tools |
- |---|---|
- | **People** | `create_person`, `get_person`, `update_person`, `list_people`, `delete_person` |
- | **Companies** | `create_company`, `get_company`, `update_company`, `list_companies`, `delete_company` |
- | **Opportunities** | `create_opportunity`, `get_opportunity`, `update_opportunity`, `list_opportunities`, `delete_opportunity` |
- | **Notes** | `create_note` (with record targets), `get_note`, `update_note`, `list_notes`, `delete_note` |
- | **Tasks** | `create_task` (with record targets + assignee), `get_task`, `update_task`, `list_tasks`, `delete_task` |
- | **Batch** | `batch_create_people`, `batch_create_companies` (up to 60 records) |
- | **Workspace** | `list_workspace_members` (for task assignment) |
- | **Metadata** | `get_metadata_objects`, `get_object_metadata` |
- | **Search** | `search_records` (across people, companies, opportunities, notes, tasks) |
- ### Composite fields, handled for you
- Twenty stores identity/contact/money data in composite fields. This server accepts flat parameters and maps them to the shapes the API expects:
- | You pass | Twenty receives |
- |---|---|
- | `firstName`, `lastName` | `name: { firstName, lastName }` |
- | `email` | `emails: { primaryEmail, additionalEmails: [] }` |
- | `phone` | `phones: { primaryPhoneNumber, ... }` |
- | `linkedinUrl` / `xUrl` / `domainName` | `{ primaryLinkUrl, ... }` link composites |
- | `amount: 12000` + `currencyCode` | `amount: { amountMicros: 12000000000, currencyCode }` |
- | `body` (notes/tasks) | `bodyV2: { markdown }` |
- | `address` (string) | `address: { addressStreet1, ... }` (or pass a full address object) |
- Anything else — including your workspace's custom fields — passes through untouched.
- > **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).
- ## 🔍 Search, filtering & pagination
- Twenty's REST API has no `search` or `offset` query params — this server builds real filters instead:
- - **`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).
- - **`filter`** accepts Twenty's raw filter grammar for anything more specific:
- - `createdAt[gte]:2026-01-01`
- - `or(city[eq]:Austin,city[eq]:Dallas)`
- - `emails.primaryEmail[ilike]:%@acme.com`
- - 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.
- - **`orderBy`**: e.g. `createdAt[DescNullsLast]` (directions: `AscNullsFirst`, `AscNullsLast`, `DescNullsFirst`, `DescNullsLast`).
- - **Pagination is cursor-based**: results include `pageInfo.endCursor` — pass it as `startingAfter` for the next page. `limit` max is 200.
- - **`depth`**: `0` (default) or `1` to include first-level related records.
- ## 🐳 Docker
- ```bash
- docker build -t twenty-crm-mcp-server .
- ```
- ```json
- {
- "mcpServers": {
- "twenty-crm": {
- "command": "docker",
- "args": ["run", "-i", "--rm", "-e", "TWENTY_API_KEY", "-e", "TWENTY_BASE_URL", "twenty-crm-mcp-server"],
- "env": {
- "TWENTY_API_KEY": "your_api_key_here",
- "TWENTY_BASE_URL": "https://api.twenty.com"
- }
- }
- }
- }
- ```
- ## 🧪 Development
- ```bash
- npm install
- npm test # unit tests (node --test, no network needed)
- npm start # run the stdio server
- ```
- ## ⬆️ Upgrading from v1.x
- v2.0.0 fixes writes and search against the actual Twenty API. Breaking changes:
- - `offset` was removed from list tools (Twenty's REST API never supported it) — use cursor pagination (`startingAfter`).
- - Note/task `body` now maps to `bodyV2.markdown`; `position` params were dropped.
- - Updates now use `PATCH` (Twenty's documented verb) instead of `PUT`.
- - List results are returned as `{ records, pageInfo, totalCount? }` instead of the raw API envelope.
- ## 🤝 Contributing
- 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).
- 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.
- ## 📄 License
- MIT — see [LICENSE](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.