Twenty CRM MCP Server

Overview

This repository contains a Twenty CRM MCP (Model Context Protocol) server that enables AI agents to interact with Twenty CRM data through both GraphQL and REST APIs. This MCP server provides comprehensive CRM capabilities including:

Person Management - Create, read, update, and delete person records
Company Management - Manage company data and relationships
Opportunity Management - Track and manage sales opportunities
Note Management - Create and manage notes across entities
Task Management - Handle task creation and updates
Custom Object Support - Work with custom objects defined in your Twenty CRM workspace

The server follows the Model Context Protocol specification, allowing AI agents to seamlessly integrate Twenty CRM functionality into their workflows using both GraphQL and REST endpoints.

Features

Dual API Support: Full support for both GraphQL and REST APIs
Core Entities: Pre-built tools for Person, Company, Opportunity, Note, and Task objects
Custom Objects: Extensible architecture to add support for custom Twenty objects
MCP Compliance: Full compatibility with the Model Context Protocol specification
Agent Gateway Integration: Automatic registration with Agent Gateway for service discovery
Interactive Web Interface: Browser-based testing with automatic session management
Dynamic curl Examples: Copy-paste ready commands that work from any host
Containerized Deployment: K8s-ready for easy deployment and scaling
Type-Safe: Built with TypeScript for robust type checking
Graceful Shutdown: Proper cleanup and gateway unregistration

Prerequisites

Node.js 18+ and npm
TypeScript 5.0+
Docker Desktop (for containerized deployment)
kubectl v1.20+ (for Kubernetes deployment)
MCP Inspector (installed via npm)
Twenty CRM Instance: Either self-hosted or cloud instance
Twenty API Key: Generate from Settings → APIs & Webhooks in your Twenty workspace

Quick Start

The fastest way to get started is using the provided Makefile:

# Initial setup (installs dependencies and creates .env)
make setup

# Edit .env with your Twenty CRM API key
nano .env

# Start development server
make dev

Visit http://localhost:5008 to access the interactive interface.

For detailed instructions, see QUICKSTART.md.

Using the Makefile

This project includes a comprehensive Makefile for all common operations:

# View all available commands
make help

# Development
make dev              # Start development server
make build            # Build TypeScript project
make test             # Run tests
make test-coverage    # Run tests with coverage

# Docker
make docker-build     # Build Docker image
make docker-run       # Run container
make docker-stop      # Stop container
make docker-logs      # View container logs

# Kubernetes
make deploy           # Deploy to Kubernetes
make k8s-status       # Check deployment status
make k8s-logs         # View pod logs
make k8s-restart      # Restart deployment

# Utilities
make clean            # Clean build artifacts
make info             # Show project info
make health           # Check server health

Run make help to see all available commands.

Configuration

Twenty CRM Setup

Log into your Twenty CRM instance
Navigate to Settings → APIs & Webhooks
Click + Create key to generate an API key
Copy the API key (shown only once)
Configure the key with appropriate permissions

Environment Variables

Create a .env file in the root directory:

# Twenty CRM Configuration
TWENTY_API_URL=https://api.twenty.com  # or your self-hosted URL
TWENTY_API_KEY=your_api_key_here

# Server Configuration
PORT=5008

For self-hosted instances, use your domain:

TWENTY_API_URL=https://your-domain.com

Local Development

Installation

Option 1: Using Makefile (Recommended)

# Initial setup - installs dependencies and creates .env
make setup

# Edit .env with your API key
nano .env  # or your preferred editor

# Start development server
make dev

# Open MCP Inspector (in new terminal)
make inspect

Option 2: Using npm directly

Clone the repository
Install dependencies:
```
npm install
```

Create and configure .env:

cp .env.example .env
# Edit .env with your Twenty CRM API key

Build the TypeScript project:
```
npm run build
```
Start the MCP server:
```
npm run mcp
```
Access the server:
- Home Page: http://localhost:5008/ (interactive testing interface)
- MCP Endpoint: http://localhost:5008/mcp
- Health Check: http://localhost:5008/health
(Optional) Open the MCP Inspector:
```
npm run mcp-inspect
```
The MCP Inspector will open at http://localhost:6274 for advanced debugging.

Testing with the Interactive Web Interface

The home page provides an interactive testing interface with:

Quick Start Guide: Step-by-step instructions with visual feedback
Session Management: Automatic session creation and ID capture
Tool Testing: One-click curl command execution for all Twenty CRM operations
Dynamic Examples: Commands automatically adapt to your host/port

Quick Test Workflow:

Visit http://localhost:5008/
Click "Initialize & Get Session" to create an MCP session
Click "Copy Command" to copy tool calls with your session ID
Paste into your terminal to execute Twenty CRM operations

All curl commands shown on the home page work from any host - they dynamically use the server's actual URL.

Available Tools

Person Tools

create-person - Create a new person record
get-person - Retrieve person by ID
update-person - Update person information
delete-person - Delete a person record
list-persons - List all persons with optional filtering

Company Tools

create-company - Create a new company
get-company - Retrieve company by ID
update-company - Update company information
delete-company - Delete a company record
list-companies - List all companies with optional filtering

Opportunity Tools

create-opportunity - Create a new sales opportunity
get-opportunity - Retrieve opportunity by ID
update-opportunity - Update opportunity details
delete-opportunity - Delete an opportunity
list-opportunities - List all opportunities with filtering

Note Tools

create-note - Create a note attached to any entity
list-notes - List notes with filtering options

Task Tools

create-task - Create a task
update-task - Update task status and details
list-tasks - List tasks with filtering

API Support

GraphQL API

Endpoint: /graphql
Supports batch operations, complex queries, and relationship traversal
Used for operations requiring multiple related entities

REST API

Endpoint: /rest
Supports CRUD operations with simple request/response patterns
Ideal for straightforward single-entity operations

Both APIs support the same core operations - choose based on your needs.

Docker Setup

Port Configuration

Internal Container Port: 8080 (configured in Dockerfile)
External Host Port: 5008 (mapped via Docker port binding)
Port Mapping: -p 5008:8080 maps external port 5008 to internal port 8080

Docker Commands

Build the Docker image:
```
npm run docker-build
```
Run the Docker container:
```
npm run docker-run
```
This runs the container in detached mode with port mapping 5008:8080.
Stop the Docker container:
```
npm run docker-stop
```

Access the running server:

# Interactive home page with testing interface
open http://localhost:5008/

# MCP protocol endpoint
curl http://localhost:5008/mcp

# Health check
curl http://localhost:5008/health

Available Scripts

Development Commands

Command	Description
`npm run build`	Build TypeScript project to `build/` directory
`npm start`	Start MCP server (port 5008)
`npm run mcp`	Start MCP server with Inspector
`npm run mcp-inspect`	Open MCP Inspector only
`npm test`	Run test suite
`npm run test:coverage`	Run tests with coverage report

Docker Commands

Command	Description
`npm run docker-build`	Build Docker image
`npm run docker-run`	Run container (detached, port 5008:8080)
`npm run docker-stop`	Stop and remove running container
`npm run build:k3d`	Build and import into k3d cluster

Deployment Commands

Command	Description
`npm run deploy`	Deploy to Kubernetes using k8s/deployment.yaml
`npm run deploy:watch`	Deploy and watch rollout status
`npm run build:deploy`	Complete workflow: build → deploy → monitor

Testing the Server

Option 1: Interactive Web Interface (Recommended)

Visit http://localhost:5008/ for the interactive testing interface.

The home page provides:

One-click session initialization
Copy-paste ready curl commands with automatic session ID injection
Real-time testing without manual session management
Examples for all Twenty CRM operations

Option 2: MCP Inspector

Use the MCP Inspector for advanced debugging:

npx @modelcontextprotocol/inspector --transport http --server-url http://localhost:5008/mcp

Architecture

The server follows a clean architecture pattern:

src/
├── application/          # Application layer (tools, handlers)
│   └── tools/           # MCP tools for each entity
├── domain/              # Domain logic (business rules)
├── infrastructure/      # External services (API clients, logging)
│   └── clients/        # Twenty CRM API clients
└── types/              # TypeScript type definitions

Learn More

Twenty CRM Documentation: https://docs.twenty.com/
Twenty API Reference: https://docs.twenty.com/developers/extend/capabilities/apis
Model Context Protocol: https://modelcontextprotocol.io/

License

Security

Store API keys securely using environment variables
Never commit .env files to version control
Rotate API keys regularly
Use appropriate role-based permissions in Twenty CRM
Review security settings before production deployment

Twenty CRM MCP Server

Overview

Person Management - Create, read, update, and delete person records
Company Management - Manage company data and relationships
Opportunity Management - Track and manage sales opportunities
Note Management - Create and manage notes across entities
Task Management - Handle task creation and updates
Custom Object Support - Work with custom objects defined in your Twenty CRM workspace

The server follows the Model Context Protocol specification, allowing AI agents to seamlessly integrate Twenty CRM functionality into their workflows using both GraphQL and REST endpoints.

Features

Dual API Support: Full support for both GraphQL and REST APIs
Core Entities: Pre-built tools for Person, Company, Opportunity, Note, and Task objects
Custom Objects: Extensible architecture to add support for custom Twenty objects
MCP Compliance: Full compatibility with the Model Context Protocol specification
Agent Gateway Integration: Automatic registration with Agent Gateway for service discovery
Interactive Web Interface: Browser-based testing with automatic session management
Dynamic curl Examples: Copy-paste ready commands that work from any host
Containerized Deployment: K8s-ready for easy deployment and scaling
Type-Safe: Built with TypeScript for robust type checking
Graceful Shutdown: Proper cleanup and gateway unregistration

Prerequisites

Node.js 18+ and npm
TypeScript 5.0+
Docker Desktop (for containerized deployment)
kubectl v1.20+ (for Kubernetes deployment)
MCP Inspector (installed via npm)
Twenty CRM Instance: Either self-hosted or cloud instance
Twenty API Key: Generate from Settings → APIs & Webhooks in your Twenty workspace

Quick Start

The fastest way to get started is using the provided Makefile:

# Initial setup (installs dependencies and creates .env)
make setup

# Edit .env with your Twenty CRM API key
nano .env

# Start development server
make dev

Visit http://localhost:5008 to access the interactive interface.

For detailed instructions, see QUICKSTART.md.

Using the Makefile

This project includes a comprehensive Makefile for all common operations:

# View all available commands
make help

# Development
make dev              # Start development server
make build            # Build TypeScript project
make test             # Run tests
make test-coverage    # Run tests with coverage

# Docker
make docker-build     # Build Docker image
make docker-run       # Run container
make docker-stop      # Stop container
make docker-logs      # View container logs

# Kubernetes
make deploy           # Deploy to Kubernetes
make k8s-status       # Check deployment status
make k8s-logs         # View pod logs
make k8s-restart      # Restart deployment

# Utilities
make clean            # Clean build artifacts
make info             # Show project info
make health           # Check server health

Run make help to see all available commands.

Configuration

Twenty CRM Setup

Log into your Twenty CRM instance
Navigate to Settings → APIs & Webhooks
Click + Create key to generate an API key
Copy the API key (shown only once)
Configure the key with appropriate permissions

Environment Variables

Create a .env file in the root directory:

# Twenty CRM Configuration
TWENTY_API_URL=https://api.twenty.com  # or your self-hosted URL
TWENTY_API_KEY=your_api_key_here

# Server Configuration
PORT=5008

For self-hosted instances, use your domain:

TWENTY_API_URL=https://your-domain.com

Local Development

Installation

Option 1: Using Makefile (Recommended)

# Initial setup - installs dependencies and creates .env
make setup

# Edit .env with your API key
nano .env  # or your preferred editor

# Start development server
make dev

# Open MCP Inspector (in new terminal)
make inspect

Option 2: Using npm directly

Clone the repository
Install dependencies:
```
npm install
```

Create and configure .env:

cp .env.example .env
# Edit .env with your Twenty CRM API key

Build the TypeScript project:
```
npm run build
```
Start the MCP server:
```
npm run mcp
```
Access the server:
- Home Page: http://localhost:5008/ (interactive testing interface)
- MCP Endpoint: http://localhost:5008/mcp
- Health Check: http://localhost:5008/health
(Optional) Open the MCP Inspector:
```
npm run mcp-inspect
```
The MCP Inspector will open at http://localhost:6274 for advanced debugging.

Testing with the Interactive Web Interface

The home page provides an interactive testing interface with:

Quick Start Guide: Step-by-step instructions with visual feedback
Session Management: Automatic session creation and ID capture
Tool Testing: One-click curl command execution for all Twenty CRM operations
Dynamic Examples: Commands automatically adapt to your host/port

Quick Test Workflow:

Visit http://localhost:5008/
Click "Initialize & Get Session" to create an MCP session
Click "Copy Command" to copy tool calls with your session ID
Paste into your terminal to execute Twenty CRM operations

All curl commands shown on the home page work from any host - they dynamically use the server's actual URL.

Available Tools

Person Tools

create-person - Create a new person record
get-person - Retrieve person by ID
update-person - Update person information
delete-person - Delete a person record
list-persons - List all persons with optional filtering

Company Tools

create-company - Create a new company
get-company - Retrieve company by ID
update-company - Update company information
delete-company - Delete a company record
list-companies - List all companies with optional filtering

Opportunity Tools

create-opportunity - Create a new sales opportunity
get-opportunity - Retrieve opportunity by ID
update-opportunity - Update opportunity details
delete-opportunity - Delete an opportunity
list-opportunities - List all opportunities with filtering

Note Tools

create-note - Create a note attached to any entity
list-notes - List notes with filtering options

Task Tools

create-task - Create a task
update-task - Update task status and details
list-tasks - List tasks with filtering

API Support

GraphQL API

Endpoint: /graphql
Supports batch operations, complex queries, and relationship traversal
Used for operations requiring multiple related entities

REST API

Endpoint: /rest
Supports CRUD operations with simple request/response patterns
Ideal for straightforward single-entity operations

Both APIs support the same core operations - choose based on your needs.

Docker Setup

Port Configuration

Internal Container Port: 8080 (configured in Dockerfile)
External Host Port: 5008 (mapped via Docker port binding)
Port Mapping: -p 5008:8080 maps external port 5008 to internal port 8080

Docker Commands

Build the Docker image:
```
npm run docker-build
```
Run the Docker container:
```
npm run docker-run
```
This runs the container in detached mode with port mapping 5008:8080.
Stop the Docker container:
```
npm run docker-stop
```

Access the running server:

# Interactive home page with testing interface
open http://localhost:5008/

# MCP protocol endpoint
curl http://localhost:5008/mcp

# Health check
curl http://localhost:5008/health

Available Scripts

Development Commands

Command	Description
`npm run build`	Build TypeScript project to `build/` directory
`npm start`	Start MCP server (port 5008)
`npm run mcp`	Start MCP server with Inspector
`npm run mcp-inspect`	Open MCP Inspector only
`npm test`	Run test suite
`npm run test:coverage`	Run tests with coverage report

Docker Commands

Command	Description
`npm run docker-build`	Build Docker image
`npm run docker-run`	Run container (detached, port 5008:8080)
`npm run docker-stop`	Stop and remove running container
`npm run build:k3d`	Build and import into k3d cluster

Deployment Commands

Command	Description
`npm run deploy`	Deploy to Kubernetes using k8s/deployment.yaml
`npm run deploy:watch`	Deploy and watch rollout status
`npm run build:deploy`	Complete workflow: build → deploy → monitor

Testing the Server

Option 1: Interactive Web Interface (Recommended)

Visit http://localhost:5008/ for the interactive testing interface.

The home page provides:

One-click session initialization
Copy-paste ready curl commands with automatic session ID injection
Real-time testing without manual session management
Examples for all Twenty CRM operations

Option 2: MCP Inspector

Use the MCP Inspector for advanced debugging:

npx @modelcontextprotocol/inspector --transport http --server-url http://localhost:5008/mcp

Architecture

The server follows a clean architecture pattern:

src/
├── application/          # Application layer (tools, handlers)
│   └── tools/           # MCP tools for each entity
├── domain/              # Domain logic (business rules)
├── infrastructure/      # External services (API clients, logging)
│   └── clients/        # Twenty CRM API clients
└── types/              # TypeScript type definitions

Learn More

Twenty CRM Documentation: https://docs.twenty.com/
Twenty API Reference: https://docs.twenty.com/developers/extend/capabilities/apis
Model Context Protocol: https://modelcontextprotocol.io/

License

Security

Store API keys securely using environment variables
Never commit .env files to version control
Rotate API keys regularly
Use appropriate role-based permissions in Twenty CRM
Review security settings before production deployment