Twenty MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with the Twenty CRM API, enabling LLM agents to interact with your CRM data through well-defined, typed tools.

📋 Table of Contents

• Overview
• Prerequisites
• Quick Start
• Installation
• Configuration
• OAuth Authentication
• Verification
• IDE Integration
• Usage
• Troubleshooting
• Additional Resources

Overview

This MCP server transforms your Twenty CRM instance into a powerful tool accessible by Claude and other MCP-compatible AI assistants. It provides comprehensive access to contacts, companies, tasks, and notes with full TypeScript support and robust error handling.

Key Features

• 🤝 Contact Management: Create, retrieve, update, and search contacts
• 🏢 Company Management: Full company lifecycle management
• 💼 Opportunity Tracking: Complete sales pipeline management
• 📝 Activity Management: Unified timeline view with filtering
• ✅ Task Management: Create and manage tasks
• 🔗 Relationship Management: Link entities and analyze connections
• 🔍 Metadata Discovery: Explore CRM schema and field definitions
• 🔐 OAuth 2.1 Authentication: Secure user-specific API key management
• 🔒 Full TypeScript Support: Type-safe operations with validation

Total: 29 MCP Tools providing comprehensive CRM automation capabilities. See full tool list →

Understanding MCP Servers

MCP (Model Context Protocol) servers are tools that extend AI assistants like Claude with new capabilities. Once configured, this server allows Claude to:

• 🔍 Read your CRM data (contacts, companies, opportunities)
• ✍️ Create new records directly from conversations
• 🔄 Update existing information
• 🤖 Automate CRM workflows through natural language

Think of it as giving Claude direct access to your Twenty CRM, turning it into a powerful CRM assistant.

Prerequisites

Before installing, ensure you have:

• ✅ Node.js 18 or higher - Download from nodejs.org
• ✅ npm (included with Node.js)
• ✅ Git for cloning the repository
• ✅ Twenty CRM instance with API access
• ✅ Text editor for configuration files

Checking Prerequisites

# Check Node.js version (should be 18+)
node --version

# Check npm is installed
npm --version

# Check git is installed
git --version

⚠️ Windows Users: The quick install script requires Git Bash or WSL. See Windows Installation Guide for alternatives.

🚀 Quick Start

Option 1: Instant Trial (No Installation Required) ⚡

# Try instantly with npx - no installation needed!
npx twenty-mcp-server setup

# Test your configuration
npx twenty-mcp-server test

# Start the server
npx twenty-mcp-server start

Perfect for trying Twenty MCP Server before committing to installation!

Option 2: Global Installation (Best for Regular Use)

# Install globally with npm
npm install -g twenty-mcp-server

# Run the interactive setup wizard
twenty-mcp setup

# Start the server
twenty-mcp start

That’s it! The CLI will guide you through everything else.

Option 3: Git Clone (For Developers)

For experienced users who want to clone and modify the source:

# Clone, install, configure, and run
git clone https://github.com/jezweb/twenty-mcp.git && \
cd twenty-mcp && \
chmod +x install.sh && \
./install.sh && \
cp .env.example .env && \
echo "Now edit .env with your API key and base URL" && \
nano .env

Then configure your IDE using the absolute path shown by the installer.

Installation

🗺️ Installation Overview

┌─────────────────┐     ┌──────────────┐     ┌──────────────┐     ┌─────────────┐
│ 1. Install      │ --> │ 2. Configure │ --> │ 3. Verify    │ --> │ 4. Connect  │
│    - Clone repo │     │    - API key │     │    - Validate│     │    - IDE    │
│    - Build      │     │    - Base URL│     │    - Test    │     │    - Use!   │
└─────────────────┘     └──────────────┘     └──────────────┘     └─────────────┘
     (~3 min)                (~2 min)             (~1 min)            (~2 min)

Choose Your Installation Method

Option 0: Docker MCP (Docker Desktop Users)

If you have Docker Desktop with MCP Toolkit enabled:

1. Open Docker Desktop
2. Go to MCP Catalog
3. Search for “Twenty CRM”
4. Click Install and configure your API key

Or use the Docker CLI:

docker mcp install twenty-mcp

Learn more at hub.docker.com/mcp

Option 1: npx Instant Trial (Try Before Installing)

Experience Twenty MCP Server instantly without any installation:

# Try it right now - no installation required!
npx twenty-mcp-server setup

# Configuration is saved globally for future npx runs
npx twenty-mcp-server test

# Start using it immediately
npx twenty-mcp-server start

Benefits:

• ✅ Zero installation - try instantly
• ✅ Always runs the latest version
• ✅ Configuration persists between runs
• ✅ Perfect for testing and evaluation
• ✅ No global installation clutter

Ready to install permanently? Simply run: npm install -g twenty-mcp-server

Option 2: npm Global Install (Best for Regular Use)

For users who want Twenty MCP Server permanently installed:

# Install globally
npm install -g twenty-mcp-server

# Verify installation
twenty-mcp --version

# Run setup wizard
twenty-mcp setup

Benefits:

• ✅ Works on all platforms (Windows, macOS, Linux)
• ✅ Automatic PATH configuration
• ✅ Interactive setup wizard guides you through everything
• ✅ No manual file management or path configuration
• ✅ Easy updates with npm update -g twenty-mcp-server
• ✅ Built-in CLI commands for management and testing
• ✅ Professional configuration management

What the setup wizard configures:

• 🔧 Twenty CRM API connection
• 🔐 OAuth 2.1 authentication (optional)
• 🛡️ IP address protection (optional)
• ⚙️ Server preferences and defaults
• 📁 Cross-platform configuration storage

Option 3: Git Clone Installation

For developers who want to modify the source code:

# Step 1: Clone the repository
git clone https://github.com/jezweb/twenty-mcp.git
cd twenty-mcp

# Step 2: Make install script executable (Linux/macOS only)
chmod +x install.sh

# Step 3: Run the installation
./install.sh

The install script will:

• ✅ Check Node.js version (18+ required)
• ✅ Install all dependencies
• ✅ Build the TypeScript project
• ✅ Run tests (if API key is configured)
• ✅ Show your absolute path for IDE configuration
• ✅ Provide next steps

📝 Note: Save the absolute path shown by the installer - you’ll need it for IDE configuration!

Option 4: Manual Installation

Perfect for Windows Command Prompt users or those who prefer manual control:

# Step 1: Clone the repository
git clone https://github.com/jezweb/twenty-mcp.git
cd twenty-mcp

# Step 2: Install dependencies
npm install

# Step 3: Build the TypeScript project
npm run build

# Step 4: Verify the build succeeded
# Linux/macOS:
ls -la dist/index.js

# Windows:
dir dist\index.js

✅ If you see dist/index.js, the build succeeded!

📍 Finding Your Installation Path (IMPORTANT!)

🚨 Critical: You MUST use the absolute path to dist/index.js for IDE configuration. Relative paths will NOT work!

Your MCP server path will be: [absolute-path]/dist/index.js

🧪 Installation Quick Check

Before proceeding to configuration, verify your installation:

# 1. Check Node modules installed
test -d node_modules && echo "✅ Dependencies installed" || echo "❌ Run: npm install"

# 2. Check build completed
test -f dist/index.js && echo "✅ Build successful" || echo "❌ Run: npm run build"

# 3. Check your path
echo "📍 Your MCP path: $(pwd)/dist/index.js"

Windows Installation Guide

🪟 Windows Users: See our detailed Windows Installation Guide for step-by-step instructions with Command Prompt, PowerShell, and Git Bash options.

Configuration

Step 1: Get Your Twenty CRM API Key

1. Log into your Twenty CRM instance

   • For Twenty Cloud: https://app.twenty.com
   • For self-hosted: Your instance URL

2. Navigate to Settings

   • Click on your profile avatar (top right)
   • Select “Settings” from the dropdown

3. Find API & Webhooks

   • Look in the “Developers” section
   • Click on “API & Webhooks”

4. Generate Your API Key

   • Click “Generate API Key” button
   • Important: Copy the key immediately - it won’t be shown again!
   • Store it securely (password manager recommended)

Step 2: Configure Environment Variables

Option A: Using .env File (Recommended)

# Copy the example configuration
cp .env.example .env

# Edit with your favorite editor
nano .env  # or vim, code, notepad, etc.

Add your configuration to the .env file:

# Your Twenty CRM API Key (from Step 1)
TWENTY_API_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Your Twenty instance URL (no trailing slash!)
TWENTY_BASE_URL=https://api.twenty.com

Common Base URLs:

• Twenty Cloud: https://api.twenty.com
• Self-hosted: https://your-company.twenty.com
• Local development: http://localhost:3000

Option B: Using Export Commands

# Linux/macOS
export TWENTY_API_KEY="your-api-key-here"
export TWENTY_BASE_URL="https://api.twenty.com"

# Windows (Command Prompt)
set TWENTY_API_KEY=your-api-key-here
set TWENTY_BASE_URL=https://api.twenty.com

# Windows (PowerShell)
$env:TWENTY_API_KEY="your-api-key-here"
$env:TWENTY_BASE_URL="https://api.twenty.com"

Step 3: Load Your Configuration

📌 Important: Environment variables must be loaded in your current shell session!

If using a .env file:

# Linux/macOS - Load variables into current session
source .env

# Verify they're loaded
echo $TWENTY_API_KEY  # Should show your key

# Windows - npm scripts read .env automatically
# No manual loading needed for npm commands

OAuth Authentication

The Twenty MCP Server supports OAuth 2.1 authentication following the MCP Authentication Specification. This enables secure, user-specific API key management and multi-user deployments.

🔐 OAuth Features

• 🔒 Secure API Key Storage: User API keys encrypted with AES-256-GCM
• 👤 User-Specific Access: Each user manages their own Twenty CRM connection
• 🔄 Backward Compatible: Works alongside traditional API key configuration
• 🛡️ Clerk Integration: Production-ready authentication provider
• 📋 Discovery Endpoints: Full MCP OAuth specification compliance

🚀 Quick OAuth Setup

Run the interactive OAuth setup CLI:

npm run setup:oauth

This will guide you through:

1. Enabling OAuth authentication
2. Configuring Clerk credentials
3. Setting up encryption secrets
4. Testing the integration

📚 OAuth Documentation

For detailed OAuth implementation guide, see OAUTH.md:

• Complete OAuth 2.1 Flow: Step-by-step implementation
• Security Best Practices: Encryption, token validation, CORS
• Client Integration Examples: JavaScript, Python, curl
• Production Deployment: Environment setup and troubleshooting

🧪 OAuth Testing

Test your OAuth setup:

# Run comprehensive OAuth test suite
npm run test:oauth

# Test specific OAuth endpoints
curl http://localhost:3000/.well-known/oauth-protected-resource
curl http://localhost:3000/.well-known/oauth-authorization-server

⚙️ OAuth vs API Key Configuration

Choose API Key mode for:

• Single-user deployments
• Simple integrations
• Quick prototyping

Choose OAuth mode for:

• Multi-user applications
• Production deployments
• Enhanced security requirements

Verification

Before configuring your IDE, verify everything is working:

1. Run Configuration Validator

npm run validate

Expected output when everything is configured:

==================================================
  Twenty MCP Server Configuration Validator
==================================================

[INFO] Checking environment variables...
[SUCCESS] TWENTY_API_KEY is set
[SUCCESS] API key appears to be in JWT format
[SUCCESS] TWENTY_BASE_URL is set: https://api.twenty.com
[SUCCESS] Base URL is valid
[INFO] Checking configuration files...
[SUCCESS] .env file exists
[INFO] Checking project build...
[SUCCESS] Project is built (dist/index.js exists)
[SUCCESS] Dependencies are installed
[INFO] Testing API connection...
[SUCCESS] API connection successful!
[INFO] Connected as: John Doe

==================================================
[SUCCESS] Configuration is valid! 🎉

2. Test Your Configuration

# Make sure environment is loaded
source .env  # Linux/macOS only

# Run basic tests
npm test

3. Optional: Start HTTP Server

npm start

You should see: Server running on http://localhost:3000

IDE Integration

📋 Before You Begin - Checklist

• [ ] Installation complete (dist/index.js exists)
• [ ] Configuration valid (npm run validate passes)
• [ ] Absolute path noted (from installation step)
• [ ] API key and base URL ready

🖥️ Claude Desktop

Configure Claude Desktop to use your Twenty MCP server:

1. Find Your Configuration File

2. Edit Configuration

If you installed via npm or use npx:

{
  "mcpServers": {
    "twenty-crm": {
      "command": "twenty-mcp",
      "args": ["start", "--stdio"],
      "env": {}
    }
  }
}

Note for npx users: Your configuration is automatically saved globally, so Claude Desktop will work seamlessly even when using npx!

If you cloned from Git:

{
  "mcpServers": {
    "twenty-crm": {
      "command": "node",
      "args": ["REPLACE_WITH_YOUR_ABSOLUTE_PATH/dist/index.js"],
      "env": {
        "TWENTY_API_KEY": "REPLACE_WITH_YOUR_API_KEY",
        "TWENTY_BASE_URL": "REPLACE_WITH_YOUR_BASE_URL"
      }
    }
  }
}

⚠️ Common Mistakes to Avoid:

• Using relative paths (e.g., ./dist/index.js) - won’t work!
• Forgetting to restart Claude Desktop after changes
• Missing quotes around paths with spaces
• Using wrong slashes on Windows (use / or \\)

3. Real Examples

npm Installation or npx Usage (All Platforms):

{
  "mcpServers": {
    "twenty-crm": {
      "command": "twenty-mcp",
      "args": ["start", "--stdio"],
      "env": {}
    }
  }
}

💡 npx users: This same configuration works whether you use npx twenty-mcp-server or install globally!

Git Installation Examples:

macOS Example:

{
  "mcpServers": {
    "twenty-crm": {
      "command": "node",
      "args": ["/Users/johndoe/projects/twenty-mcp/dist/index.js"],
      "env": {
        "TWENTY_API_KEY": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "TWENTY_BASE_URL": "https://api.twenty.com"
      }
    }
  }
}

Windows Example:

{
  "mcpServers": {
    "twenty-crm": {
      "command": "node",
      "args": ["C:\\Users\\johndoe\\projects\\twenty-mcp\\dist\\index.js"],
      "env": {
        "TWENTY_API_KEY": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "TWENTY_BASE_URL": "https://api.twenty.com"
      }
    }
  }
}

4. Verify Connection

1. Restart Claude Desktop (required!)
2. Ask Claude: “What MCP tools do you have available?”
3. Test with: “Show me my contacts from Twenty CRM”

💻 Other IDE Integrations

CLI Commands

Twenty MCP Server includes a powerful CLI for easy management:

Setup and Configuration

# Interactive setup wizard (recommended for first-time setup)
twenty-mcp setup

# Setup with OAuth authentication
twenty-mcp setup --oauth

# Setup with IP protection
twenty-mcp setup --ip-protection

# Import existing .env configuration
twenty-mcp setup --import

# Reset to default configuration
twenty-mcp setup --reset

Server Management

# Start the server (HTTP mode, default port 3000)
twenty-mcp start

# Start with custom port
twenty-mcp start --port 8080

# Start in stdio mode (for direct MCP protocol communication)
twenty-mcp start --stdio

# Start with verbose logging
twenty-mcp start --verbose

Testing and Diagnostics

# Test configuration and connection
twenty-mcp test

# Run full test suite including API tests
twenty-mcp test --full

# Test OAuth authentication endpoints
twenty-mcp test --oauth

# Run smoke tests only (no API calls)
twenty-mcp test --smoke

Status and Information

# Show server status and configuration
twenty-mcp status

# Show detailed status information
twenty-mcp status --verbose

# Output status in JSON format
twenty-mcp status --json

# Show help for all commands
twenty-mcp help

# Show version
twenty-mcp --version

AI Assistant Usage

Basic Commands

Once configured in your IDE, you can ask your AI assistant to:

• “Show me all contacts in Twenty CRM”
• “Create a new company called Acme Corp”
• “Find all opportunities in the proposal stage”
• “Add a task to follow up with John Doe”
• “Show me all activities from last week”

Example Conversations

You: "Create a new contact for Jane Smith at [email protected]"
Claude: I'll create a new contact for Jane Smith in your Twenty CRM...

You: "Find all opportunities worth over $10,000"
Claude: Let me search for high-value opportunities in your CRM...

You: "Show me companies without any contacts"
Claude: I'll find orphaned company records in your system...

See full tool documentation →

Troubleshooting

🔧 Quick Diagnostic

First, run the configuration validator:

npm run validate

This will identify most common issues and suggest fixes.

🚫 Common Issues & Solutions

Installation Issues

Configuration Issues

IDE Integration Issues

🔍 Advanced Debugging

Enable debug logging for more details:

# Enable all debug output
DEBUG=twenty-mcp:* npm start

# Test specific GraphQL queries
node test-graphql.js

🆘 Getting Help

If you’re still stuck:

1. Check existing issues: GitHub Issues
2. Read test documentation: TESTING.md
3. Create a new issue with:
   • Your OS and Node.js version
   • Complete error message
   • Output from npm run validate
   • Steps to reproduce

Additional Resources

📚 Documentation

• Full Tool Reference - Detailed documentation of all 29 tools
• Testing Guide - How to run and write tests
• Contributing Guide - How to contribute to the project

🏗️ Architecture

The Twenty MCP Server is built with:

• TypeScript for type safety
• GraphQL for Twenty API communication
• MCP SDK for protocol implementation
• Zod for runtime validation

See architecture details →

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Setting up development environment
• Running tests
• Submitting pull requests
• Code style guidelines

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Twenty CRM for the open-source CRM platform
• Model Context Protocol for the integration standard
• Anthropic for Claude and the MCP framework

---