twenty

Twenty MCP Server provides a bridge between Twenty CRM and the Model Context Protocol, enabling AI agents to perform CRM operations, fetch and analyze data, and receive real-time updates. Once running, it exposes an MCP-compatible service that coordinates CRM actions such as creating, reading, updating, and deleting Twenty CRM entities, while leveraging dynamic schema awareness to handle custom fields. The server also supports real-time synchronization via WebSocket updates and uses optimized GraphQL and REST API pathways to interact with Twenty.

To use it, first ensure Twenty CRM is running and reachable from the server. After starting, configure the MCP environment by supplying your Twenty API URL and API key, either through the provided setup script or by editing the environment file. The MCP server then handles discovery, API orchestration, and context management for AI assistants issuing tasks to Twenty CRM. You can test the integration using the included discovery and dev scripts, and monitor real-time updates through the WebSocket channels exposed by the server.

Prerequisites:

• Node.js 18+
• Docker (optional for deployment) and Docker Compose (optional for deployment)
• Git

Installation steps:

1. Clone the repository and install dependencies

git clone <repository-url>
cod e twenty-mcp-server
npm install

2. Start Twenty CRM (for development/testing)

# Smart start Twenty CRM (as described in docs)
npm run twenty:quick

3. Create workspace and API key in Twenty CRM as instructed by the Quick Start guide.

4. Configure MCP environment

# Setup environment file (if provided by project)
npm run twenty:setup
# Edit .env to include TWENTY_API_URL and TWENTY_API_KEY

5. Run the MCP server in development mode

npm run dev

6. Optional: Build for production

npm run build

7. Optional Docker deployment

docker build -t twenty-mcp-server .
docker run -d --env-file .env -p 3001:3001 twenty-mcp-server

Notes:

• Ensure TWENTY_API_URL points to your local Twenty CRM instance (default http://localhost:3000) and TWENTY_API_KEY is set to a valid key.
• The MCP server relies on real-time updates via WebSockets; ensure network access between the MCP server and Twenty CRM is allowed.
• For testing, use npm run discover to verify API discovery and npm run dev to start the MCP server.
• If you encounter startup issues, check logs with npm run twenty:logs and verify API keys and URL in the .env file.
• When deploying with Docker, map the internal port to the host port you intend to use (default 3001 in the example) and provide a proper env-file with credentials.