twenty-mcp¶

Twenty CRM REST/GraphQL API + MCP Server for the agent-utilities ecosystem — a typed, deterministic tool surface and Pydantic-AI agent for the Twenty customer-relationship-management platform.

Official documentation

This site is the canonical reference for twenty-mcp, maintained alongside every release.

Overview¶

twenty-mcp wraps the Twenty CRM REST and GraphQL surface with typed, deterministic MCP tools, and ships a Pydantic-AI agent that delegates CRM work to those tools. It provides:

Api — a multi-inheritance client facade (CrmApi + MetadataApi + OauthApi) over the Twenty REST/GraphQL API, built on a tolerant requests session.
Action-dispatch MCP tools — twenty_mcp_crm, twenty_mcp_metadata, and twenty_mcp_oauth, each routing a named action onto the corresponding client method, with per-domain registration switches (CRMTOOL, METADATATOOL, OAUTHTOOL).
A Pydantic-AI agent (twenty-agent console script) that connects to the MCP server over MCP_URL and exposes an HTTP API and optional web UI.

The server remains inactive against the CRM when credentials are absent — every configuration value is read from the environment.

Explore the documentation¶

Installation — pip, source, extras, and the prebuilt Docker image.
Deployment — run the MCP and agent servers, Docker Compose, Caddy + Technitium.
Usage — the MCP tools, the Api client, and example prompts.
Backing Platform — deploy Twenty CRM with Docker.
Overview — the dynamic facade architecture.
Concepts — the CONCEPT:TWENTY-* registry.

Quick start¶

pip install "twenty-mcp[mcp]"
twenty-mcp                       # stdio MCP server (default transport)

Connect it to a Twenty CRM instance:

export TWENTY_URL=http://your-twenty:3000
export TWENTY_TOKEN=your_developer_access_token
twenty-mcp --transport streamable-http --host 0.0.0.0 --port 8000

See Installation and Deployment for the full matrix (PyPI extras, Docker image, all transports, the agent server, reverse proxy, DNS).