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:

# 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

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:

# 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

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

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

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