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

⚠️ 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) ⚡

Perfect for trying Twenty MCP Server before committing to installation!

Option 2: Global Installation (Best for Regular Use)

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:

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

Installation

🗺️ Installation Overview

Choose Your Installation Method

Option 1: npx Instant Trial (Try Before Installing)

Experience Twenty MCP Server instantly without any installation:

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:

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:

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:

✅ 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!

⚠️ Warning: If your path contains spaces (e.g., "Program Files"), use quotes in your IDE configuration!

Your MCP server path will be:

🧪 Installation Quick Check

Before proceeding to configuration, verify your installation:

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)

Add your configuration to the .env file:

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

Step 3: Load Your Configuration

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

.env files store configuration but don't automatically load into your shell:

• Linux/macOS: Must use source .env to load variables

• Windows: The npm scripts automatically read .env files

• IDE Configuration: Usually reads .env files directly

If using a .env file:

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:

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:

⚙️ 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

Expected output when everything is configured:

2. Test Your Configuration

3. Optional: Start HTTP Server

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:

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:

⚠️ 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):

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

Git Installation Examples:

macOS Example:

Windows Example:

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

1. Open Cursor Settings (Cmd/Ctrl + ,)

2. Navigate to Extensions → MCP Servers

3. Add configuration:

   { "name": "twenty-crm", "command": "node", "args": ["/absolute/path/to/twenty-mcp/dist/index.js"], "env": { "TWENTY_API_KEY": "your-api-key", "TWENTY_BASE_URL": "https://your-instance.com" } }

4. Restart Cursor

Full Smithery Guide →

Quick setup:

1. Install Smithery: npm install -g @smithery/cli

2. Run: smithery dev in the twenty-mcp directory

3. Configure credentials when prompted

Or use the deployed version:

• Visit smithery.ai

• Search for "Twenty MCP"

• Click "Use this server"

1. Install Cline extension from VS Code marketplace

2. Add to VS Code settings.json:

   { "cline.mcpServers": { "twenty-crm": { "command": "node", "args": ["/path/to/twenty-mcp/dist/index.js"], "env": { "TWENTY_API_KEY": "your-api-key", "TWENTY_BASE_URL": "https://your-instance.com" } } } }

For web integrations, run as HTTP server:

Configure via query parameters:

CLI Commands

Twenty MCP Server includes a powerful CLI for easy management:

Setup and Configuration

Server Management

Testing and Diagnostics

Status and Information

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

See full tool documentation →

Troubleshooting

🔧 Quick Diagnostic

First, run the configuration validator:

This will identify most common issues and suggest fixes.

🚫 Common Issues & Solutions

Installation Issues

Solution: Update Node.js

Solution: Build the project

Solution: Make script executable

Configuration Issues

Solution: Set your environment variables

Solution:

1. Verify API key is correct (no extra spaces)

2. Check key hasn't expired

3. Regenerate key in Twenty CRM Settings

4. Ensure you're using the correct base URL

Solution:

1. Check base URL is correct (no trailing slash!)

2. Verify Twenty instance is accessible

3. Check firewall/proxy settings

4. Test with curl:

   curl -H "Authorization: Bearer YOUR_API_KEY" \ https://your-instance.com/graphql

IDE Integration Issues

Solution:

1. Verify absolute path is correct:

   # Get the correct path cd twenty-mcp && pwd

2. Check config file location is correct for your OS

3. Ensure JSON syntax is valid (no trailing commas!)

4. Restart Claude Desktop (required!)

5. Check Claude's developer console for errors

Solution: Use proper Windows paths

🔍 Advanced Debugging

Enable debug logging for more details:

🆘 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

Project Structure

Key Components

• TwentyClient: GraphQL client that handles API communication with Twenty CRM

• MCP Tools: 29 tools that provide comprehensive CRM functionality to AI assistants

• Type System: Comprehensive TypeScript definitions for Twenty's data structures

• Schema Transformation: Converts flat tool inputs to Twenty's nested GraphQL schema