# 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:
```bash
# 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](QUICKSTART.md).
## Using the Makefile
This project includes a comprehensive Makefile for all common operations:
```bash
# 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:
```bash
# 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:
```bash
TWENTY_API_URL=https://your-domain.com
```
## Local Development
### Installation
#### Option 1: Using Makefile (Recommended)
```bash
# 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:
```bash
npm install
```
3. Create and configure .env:
```bash
cp .env.example .env
# Edit .env with your Twenty CRM API key
```
4. Build the TypeScript project:
```bash
npm run build
```
4. Start the MCP server:
```bash
npm run mcp
```
5. Access the server:
- **Home Page**: http://localhost:5008/ (interactive testing interface)
- **MCP Endpoint**: http://localhost:5008/mcp
- **Health Check**: http://localhost:5008/health
6. (Optional) Open the MCP Inspector:
```bash
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:
```bash
npm run docker-build
```
2. Run the Docker container:
```bash
npm run docker-run
```
This runs the container in detached mode with port mapping `5008:8080`.
3. Stop the Docker container:
```bash
npm run docker-stop
```
4. Access the running server:
```bash
# 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:
```bash
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
