Twenty MCP Server

An MCP server for integrating with Twenty CRM, providing access to Twenty's REST API through categorized tools. The available tools map the entire Twenty REST API and were automatically generated using the openapi-mcp-generator.

Installation

Clone the repository and build: npm install && npm run build

Usage Instructions

The server includes usage instructions in src/instructions/instructions.md containing best practices discovered through experimentation (e.g., workflow requirements, formatting conventions, search tips). These can be customized for your specific use case by editing the file and rebuilding with npm run build.

Tool Filtering

This MCP server supports both category-based and individual tool filtering, allowing you to selectively enable only the tools you need. This approach significantly reduces context window usage and improves performance.

Available Categories

Category	Description
api-schema	API Schema & Metadata
crm	CRM & Contact Management
tasks	Task & Project Management
notes	Notes & Documentation
attachments	File Attachments
calendar	Calendar & Events
messaging	Messaging & Communication
preferences	User Preferences & Organization
views	Data Views & Filtering
workflow	Workflow & Automation
system	System & Admin

Available Tools

All available tools can be found in the Twenty REST API schema at https://your-twenty-instance.com/rest under the operationId field. You can either:

• Download the OpenAPI specification from your Twenty instance, or
• Browse tool definitions directly in this repository under the /src/tools/ directory

Usage

MCP Client Configuration

When configuring this server in an MCP client (like Claude Desktop), you can use category and/or specific tool arguments to control which tools are available.

[!TIP] Performance Recommendation
It's highly recommended to limit the available tools to only what you need. This reduces the context window size required to display available tools, improving both performance and cost efficiency.

[!NOTE] The tools defined in the "Using Specific Tools" example below represent my currently used tool setup.

Using Categories

Filter tools by predefined categories:

{
  "mcpServers": {
    "twenty": {
      "command": "node",
      "args": [
        "/path/to/twenty-mcp-server/build/index.js",
        "--category=crm,tasks,notes"
      ],
      "env": {
        "TWENTY_BASE_URL": "https://your-twenty-instance.com/rest",
        "TWENTY_API_KEY": "your-api-key"
      }
    }
  }
}

Using Specific Tools

Select individual tools by their names:

{
  "mcpServers": {
    "twenty": {
      "command": "node",
      "args": [
        "/path/to/twenty-mcp-server/build/index.js",
        "--tools=findManyCompanies, createOneCompany, findOneCompany, UpdateOneCompany, findManyPeople, createOnePerson, findOnePerson, UpdateOnePerson,findOneNote, findManyNotes, createOneNote, createManyNotes, UpdateOneNote, createOneNoteTarget, createManyNoteTargets, findManyOpportunities, createOneOpportunity, findOneOpportunity, UpdateOneOpportunity"
      ],
      "env": {
        "TWENTY_BASE_URL": "https://your-twenty-instance.com/rest",
        "TWENTY_API_KEY": "your-api-key"
      }
    }
  }
}

Combining Categories and Specific Tools

Use both approaches together:

{
  "mcpServers": {
    "twenty": {
      "command": "node",
      "args": [
        "/path/to/twenty-mcp-server/build/index.js",
        "--category=crm,tasks",
        "--tools=findManyAttachments,createOneAttachment"
      ],
      "env": {
        "TWENTY_BASE_URL": "https://your-twenty-instance.com/rest",
        "TWENTY_API_KEY": "your-api-key"
      }
    }
  }
}

---

Default Behavior

[!NOTE] Default Configuration If neither --category nor --tools arguments are provided, all categories are enabled by default. This gives you access to the complete Twenty API but will impact performance and costs due to the large number of available tools.

[!CAUTION] Development Version
This server is currently in development and is not recommended for production use. Use at your own risk in production environments. This MCP server provides access to your Twenty CRM API using your api-key. It has no built-in authorization, authentication, or access controls.