Twenty CRM

You can run a dedicated MCP server that lets AI agents interact with Twenty CRM data through both GraphQL and REST APIs. It supports core CRM entities, notes, tasks, and custom objects, and it integrates with your workflow through a standardized Model Context Protocol interface.

How to use

Start the MCP server in development or production mode and connect your MCP client to either the HTTP endpoint or the local stdio interface. You can access an interactive web testing interface at the server URL, and you can perform CRUD operations on Person, Company, Opportunity, Note, and Task objects as well as manage custom objects.

How to install

Prerequisites you need to install and run this MCP server are listed below. Prepare a local environment with Node.js and related tooling, then install dependencies and start the server.

# Prerequisites
node -v
npm -v
# Ensure Node.js 18+ and npm are available

# Optional: install MCP Inspector if you plan to debug
npm i -g @modelcontextprotocol/inspector

Configuration and startup

The server reads its configuration from environment variables. Create a .env file in the root with your Twenty CRM API settings and server port, then start the server.

# Example .env
TWENTY_API_URL=https://api.twenty.com
TWENTY_API_KEY=your_api_key_here
PORT=5008

Start the server (development mode)

Use the included development script to start the MCP server and enable the built-in inspector for debugging.

npm run mcp

Then open the interactive interface at http://localhost:5008/ and use the MCP tools to perform operations against Twenty CRM data.

## Access points

HTTP MCP endpoint (remote) at the default location: http://localhost:5008/mcp. You can also reach a web-based testing interface at http://localhost:5008/.

## Docker and Kubernetes (optional)

If you are deploying with containers, you can build and run a Docker image, then expose port 5008 to your host. For Kubernetes, use the provided deployment manifests to scale the MCP server alongside your Twenty CRM instance.

## Available tools

### create-person

Create a new person record in Twenty CRM.

### get-person

Retrieve a person by ID.

### update-person

Update person details.

### delete-person

Delete a person record.

### list-persons

List all persons with optional filtering.

### create-company

Create a new company record.

### get-company

Retrieve a company by ID.

### update-company

Update company information.

### delete-company

Delete a company record.

### list-companies

List all companies with optional filtering.

### create-opportunity

Create a new sales opportunity.

### get-opportunity

Retrieve an opportunity by ID.

### update-opportunity

Update opportunity details.

### delete-opportunity

Delete an opportunity.

### list-opportunities

List all opportunities with filtering.

### create-note

Create a note attached to any entity.

### list-notes

List notes with filtering options.

### create-task

Create a task.

### update-task

Update task status and details.

### list-tasks

List tasks with filtering.