twenty-mcp

An MCP server that connects Claude (and any MCP-compatible agent) to a Twenty CRM instance — contacts, companies, opportunities, tasks, notes, the whole pipeline. 29 tools.

Fork of jezweb/twenty-mcp. See what this fork adds below.

---

What this fork adds

Three changes over upstream, focused on making the server work cleanly with real Twenty instances (custom fields, composite types, schema drift):

1. Dynamic GraphQL schema introspection

Upstream hardcodes field selections per entity. That breaks any time Twenty adds a field or you customize the schema. This fork introspects the GraphQL schema at runtime and builds field selections on the fly, with an in-process cache so the overhead is paid once:

• Composite types (Links, Currency, Address, FullName, Emails, Phones, Actor) are expanded to their sub-fields automatically
• Connection relations, raw OBJECT fields without a known composite, TSVector, searchVector, and position are skipped so the queries never blow up on schema noise
• Falls back gracefully on introspection failure

See src/client/twenty-client.ts → getFieldFragment.

2. Custom enum field discovery for Company

If you've added custom enum fields to your Company entity in Twenty, the model now sees them as typed tool arguments — no manual schema mapping. On boot, registerCompanyTools introspects the Company metadata, pulls custom enum fields, and extends the Zod schema for create_company / update_company with z.enum([...]) for each one, with the allowed values described inline.

See src/tools/index.ts → registerCompanyTools.

3. LinkedIn URL handling on update_person

Twenty stores linkedinLink as a composite (Links) field, not a flat URL. Upstream's update_person spreads the URL flat, which Twenty rejects. This fork nests it into linkedinLink.primaryLinkUrl before the API call.

See src/tools/index.ts → update_person handler.

Diff with upstream: compare/main...IamOrbitDev:main

---

Quick start

You need a Twenty CRM instance and an API key (Twenty → Settings → API → Generate).

Try it instantly (no install)

npx @jezweb/twenty-mcp setup    # interactive config (Twenty URL + API key)
npx @jezweb/twenty-mcp start    # launch the MCP server

Or clone this fork

git clone https://github.com/IamOrbitDev/twenty-mcp.git
cd twenty-mcp
npm install
cp .env.example .env            # edit: TWENTY_API_KEY, TWENTY_BASE_URL
npm run build
npm start

Wire it to Claude Code / Desktop

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

Full IDE integration details (Claude Desktop, Cursor, Continue, etc.) in MCP_SETUP.md.

---

Configuration

Single .env file at the repo root:

TWENTY_API_KEY=<from Twenty Settings → API>
TWENTY_BASE_URL=https://your-twenty-instance.com    # no trailing slash

OAuth 2.1 (multi-user, per-user API keys) is also supported — see OAUTH.md.

---

What you can do with it

29 MCP tools across the Twenty data model:

• People / Companies — create, read, update, search
• Opportunities — full sales pipeline (create, link to company, move stage, search by stage)
• Tasks & Notes — create, list, filter
• Activities — unified timeline, filter by entity / type / date
• Relationships — link entities, find orphaned records, summarize connections
• Metadata — introspect the Twenty schema, list custom fields

Full tool list with arguments: TOOLS.md.

Example prompts the model handles well:

"Find the company Acme and list everyone who works there." "Move opportunity Q2 expansion to the Negotiating stage and add a task for me to follow up Friday." "Show me all activities tagged with the enterprise custom field this month."

---

Documentation

Doc	Purpose
MCP_SETUP.md	IDE wiring (Claude Desktop, Cursor, Continue, Windsurf, Zed, …)
TOOLS.md	Full reference for the 29 MCP tools
OAUTH.md	OAuth 2.1 setup for multi-user deployments
SMITHERY.md	Smithery platform deployment
TESTING.md	Test suite and how to run it
WINDOWS_INSTALL.md	Windows-specific install notes
CONTRIBUTING.md	Contribution guide
CHANGELOG.md	Release notes

---

Status & credit

Upstream is actively maintained by Jez. This fork keeps the changes scoped to schema-handling improvements and custom-field support. If you're using this fork in production and the changes here are useful upstream, a PR to jezweb/twenty-mcp is welcome.

License

MIT, same as upstream. See LICENSE.