# Twenty CRM MCP Server

A Model Context Protocol (MCP) server that connects [Twenty CRM](https://twenty.com) with Claude and other AI assistants, so you can manage your CRM data with natural language.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)

Repository: https://github.com/SaschaRoelofs/twenty-crm-mcp-server

## Features

- **Full CRUD** for people, companies, opportunities, tasks, and notes
- **Generic record tools** (`list_records`, `get_record`, `create_record`, `update_record`, `delete_record`) that work with any standard or custom object — including ones added after this server was written
- **Dynamic schema discovery** — automatically adapts to your Twenty CRM configuration and custom fields
- **Search** across multiple object types
- **Workflow triggering** for workflows with a webhook trigger

## Installation

### Prerequisites

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

### Setup

1. Clone the repository:
   ```bash
   git clone https://github.com/SaschaRoelofs/twenty-crm-mcp-server.git
   cd twenty-crm-mcp-server
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

3. Get your Twenty CRM API key:
   - Log in to your Twenty CRM workspace
   - Go to Settings → API & Webhooks (under Developers)
   - Generate a new API key

4. Add the server to your `claude_desktop_config.json`:
   ```json
   {
     "mcpServers": {
       "twenty-crm": {
         "command": "node",
         "args": ["/path/to/twenty-crm-mcp-server/index.js"],
         "env": {
           "TWENTY_API_KEY": "your_api_key_here",
           "TWENTY_BASE_URL": "https://api.twenty.com"
         }
       }
     }
   }
   ```
   For self-hosted Twenty instances, change `TWENTY_BASE_URL` to your own domain.

5. Restart Claude Desktop to load the server.

## Usage

Once configured, just talk to Claude naturally:

```
"List the first 10 people in my CRM"
"Create a new person named John Doe with email john@example.com"
"Show me all companies with more than 100 employees"
"Create a $10,000 opportunity called 'Acme Renewal' for Acme Corp"
"Create a task to follow up with John next Friday"
"Add a note about my meeting with the client today"
"Search for any records mentioning 'blockchain'"
"Trigger the 'Send Welcome Email' workflow for this contact"
```

## API Reference

<details>
<summary><strong>People</strong></summary>

- `create_person`, `get_person`, `update_person`, `list_people`, `delete_person`

</details>

<details>
<summary><strong>Companies</strong></summary>

- `create_company`, `get_company`, `update_company`, `list_companies`, `delete_company`

</details>

<details>
<summary><strong>Opportunities</strong></summary>

- `create_opportunity`, `get_opportunity`, `update_opportunity`, `list_opportunities`, `delete_opportunity`

</details>

<details>
<summary><strong>Tasks</strong></summary>

- `create_task`, `get_task`, `update_task`, `list_tasks`, `delete_task`

</details>

<details>
<summary><strong>Notes</strong></summary>

- `create_note`, `get_note`, `update_note`, `list_notes`, `delete_note`
- `link_note` / `unlink_note` — link or unlink a note to a person, company, or opportunity
- `list_note_targets` — list note-to-record links, optionally filtered

</details>

<details>
<summary><strong>Metadata & search</strong></summary>

- `get_metadata_objects` - Get all object types and schemas
- `get_object_metadata` - Get metadata for a specific object
- `search_records` - Search across multiple object types

</details>

<details>
<summary><strong>Generic record operations (any object type)</strong></summary>

These work with **any** standard or custom object type by its plural API name (e.g. `people`, `opportunities`, or a custom object like `projects`), so the server keeps working even if objects or fields change in your workspace. Use `get_metadata_objects` / `get_object_metadata` to discover valid object type names and fields.

- `list_records`, `get_record`, `create_record`, `update_record`, `delete_record`

</details>

<details>
<summary><strong>Workflows</strong></summary>

Workflows are standard Twenty objects, so you can already browse them with the generic tools above: `list_records`/`get_record` with `objectType` set to `workflows`, `workflowVersions`, or `workflowRuns`.

- `trigger_workflow` - Trigger a run of a workflow that has a **Webhook** trigger configured in the Twenty UI (Workflows → your workflow → Trigger → Webhook). Requires the workflow ID and a workspace ID (from `TWENTY_WORKSPACE_ID` or passed per-call).

</details>

## Configuration

| Variable | Required | Description |
|---|---|---|
| `TWENTY_API_KEY` | Yes | Your Twenty CRM API key |
| `TWENTY_BASE_URL` | No | Twenty CRM base URL (defaults to `https://api.twenty.com`) |
| `TWENTY_WORKSPACE_ID` | No | Workspace ID, needed only for `trigger_workflow`. Can also be passed per-call as `workspaceId`. |

Custom fields are discovered automatically — no configuration changes needed when you add new fields in Twenty.

## Development

```bash
git clone https://github.com/SaschaRoelofs/twenty-crm-mcp-server.git
cd twenty-crm-mcp-server
npm install
cp .env.example .env   # add your API key
npm test
```

## License

MIT