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:

1. Person Management - Create, read, update, and delete person records

2. Company Management - Manage company data and relationships

3. Opportunity Management - Track and manage sales opportunities

4. Note Management - Create and manage notes across entities

5. Task Management - Handle task creation and updates

6. 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:

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:

Run make help to see all available commands.

Configuration

Twenty CRM Setup

1. Log into your Twenty CRM instance

2. Navigate to Settings → APIs & Webhooks

3. Click + Create key to generate an API key

4. Copy the API key (shown only once)

5. Configure the key with appropriate permissions

Environment Variables

Create a .env file in the root directory:

For self-hosted instances, use your domain:

Local Development

Installation

Option 1: Using Makefile (Recommended)

Option 2: Using npm directly

1. Clone the repository

2. Install dependencies:

   npm install

3. Create and configure .env:

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

4. Build the TypeScript project:

   npm run build

5. Start the MCP server:

   npm run mcp

6. Access the server:

   • Home Page: http://localhost:5008/ (interactive testing interface)

   • MCP Endpoint: http://localhost:5008/mcp

   • Health Check: http://localhost:5008/health

7. (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:

1. Visit http://localhost:5008/

2. Click "Initialize & Get Session" to create an MCP session

3. Click "Copy Command" to copy tool calls with your session ID

4. 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

1. Build the Docker image:

   npm run docker-build

2. Run the Docker container:

   npm run docker-run

   This runs the container in detached mode with port mapping 5008:8080.

3. Stop the Docker container:

   npm run docker-stop

4. 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

Docker Commands

Deployment Commands

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:

Architecture

The server follows a clean architecture pattern:

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

Copyright © 2025. All rights reserved.

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