Twenty CRMSAFE
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
[](https://opensource.org/licenses/MIT) [](https://www.typescriptlang.org/) [](https://twenty.com/) [](https://modelcontextprotocol.io/)
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
8d310d85a21cOBSERVED · 2026-10-08Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add twenty-mcp-server --env API_KEY_ENCRYPTION_SECRET=${API_KEY_ENCRYPTION_SECRET} --env AUTH_ENABLED=${AUTH_ENABLED} --env AUTH_PROVIDER=${AUTH_PROVIDER} --env CLERK_PUBLISHABLE_KEY=${CLERK_PUBLISHABLE_KEY} -- npx -y [email protected]{
"mcpServers": {
"twenty-mcp-server": {
"command": "npx",
"args": [
"-y",
"[email protected]"
],
"env": {
"API_KEY_ENCRYPTION_SECRET": "${API_KEY_ENCRYPTION_SECRET}",
"AUTH_ENABLED": "${AUTH_ENABLED}",
"AUTH_PROVIDER": "${AUTH_PROVIDER}",
"CLERK_PUBLISHABLE_KEY": "${CLERK_PUBLISHABLE_KEY}"
}
}
}
}Exposed tools (29)
19 read · 10 write · 0 destructive.
| Tool | Risk | Description |
|---|---|---|
create_comment | write | Create a comment on any CRM record |
create_company | write | Create a new company in Twenty CRM |
create_contact | write | Create a new contact (person) in Twenty CRM |
create_note | write | Create a new note in Twenty CRM |
create_opportunity | write | Create a new opportunity/deal in Twenty CRM |
create_task | write | Create a new task in Twenty CRM |
filter_activities | read | Filter activities by specific criteria |
find_orphaned_records | read | Find records that are missing important relationships (companies without contacts, contacts without companies, etc.) |
get_activities | read | Get unified activities timeline from Twenty CRM (tasks, notes, etc.) |
get_company | read | Retrieve a company by ID from Twenty CRM |
get_company_contacts | read | Get all contacts (people) associated with a specific company |
get_contact | read | Retrieve a contact by ID from Twenty CRM |
get_entity_activities | read | Get all activities related to a specific entity (person, company, or opportunity) |
get_field_metadata | read | Get detailed information about fields, either for a specific object or across all objects |
get_object_schema | read | Get detailed schema information for a specific object including all fields and their types |
get_opportunity | read | Retrieve an opportunity by ID from Twenty CRM |
get_person_opportunities | read | Get all opportunities where a specific person is the point of contact |
get_relationship_summary | read | Get a summary of all relationships for a specific entity (company or person) |
get_tasks | read | Retrieve tasks from Twenty CRM |
link_opportunity_to_company | read | Link an opportunity to a company and/or point of contact |
list_all_objects | read | List all objects (entities) available in Twenty CRM with their metadata |
list_opportunities_by_stage | read | List all opportunities grouped by their sales stage (pipeline view) |
search_companies | read | Search for companies in Twenty CRM |
search_contacts | read | Search for contacts in Twenty CRM |
search_opportunities | read | Search for opportunities in Twenty CRM with various filters |
transfer_contact_to_company | write | Transfer a contact (person) from one company to another |
update_company | write | Update an existing company in Twenty CRM |
update_contact | write | Update an existing contact in Twenty CRM |
update_opportunity | write | Update an existing opportunity in Twenty CRM |
Trust audit
SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | WARN |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | PASS |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (1 observation(s))
- Network
- none-observed
- Shell
- declared (1 observation(s))
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (13)
console.log(`Example: http://localhost:${port}/mcp?apiKey=YOUR_API_KEY&baseUrl=https://api.twenty.com`);.env.auth-test
console.log(` Token Endpoint: ${metadata.token_endpoint}`);console.log('i️ For this demo, we\\'ll simulate the callback with a mock token');console.log(` Access Token: ${this.accessToken.substring(0, 20)}...`);const packagePath = join(__dirname, '../../package.json');
@clerk/clerk-sdk-node, @clerk/types, @modelcontextprotocol/sdk, @types/inquirer, chalk, commander, graphql, graphql-request
POST https://your-app.clerk.accounts.dev/oauth/token
# Load environment variables and run test
- **Windows**: The npm scripts automatically read .env files
# Windows - npm scripts read .env automatically
# Option 1: Load from .env file
# Load environment variables first
Gates applied: no_behavioural_pass.
8d310d85a21cfull audit observations/trust-audit/mcp-server/jezweb__twenty-crm-2.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-08 | 8d310d85a21c | SAFE | B | 89 | first audit |
Questions
What tools does Twenty CRM expose?
29 in total: 19 read-only, 10 that write, and 0 that can delete or overwrite. Every one is listed on this page with its risk.
Is Twenty CRM safe to connect to an agent?
The audit found nothing in the source that contradicts what it says it does, and graded it B (89/100). Grade A is held back for packages that have also passed a sandboxed behavioural run, which is why a clean server reads B.
What credentials does Twenty CRM need?
It reads API_KEY_ENCRYPTION_SECRET, AUTH_ENABLED, AUTH_PROVIDER, CLERK_PUBLISHABLE_KEY, CLERK_SECRET_KEY, REQUIRE_AUTH, SMITHERY_CONFIG_APIKEY and TWENTY_API_KEY from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does Twenty CRM run?
It speaks stdio and streamable-http, so it runs as a local process your client starts. It is published on npm as twenty-mcp-server at 1.3.0.
How current is this page?
The grade is for one exact copy of the source (8d310d85a21c), read on 2026-10-08. The repository is watched and re-audited when it changes.