Twenty CRM + MCP Server

Solução completa que combina o Twenty CRM com um MCP Server (Model Context Protocol) para integração avançada.

O que é?

Este projeto fornece uma stack containerizada que inclui:

• Twenty CRM - Plataforma de CRM moderna e extensível
• Twenty Worker - Processador de tarefas assíncronas
• MCP Server - Servidor Model Context Protocol para integração com IA e automações

Versão 0.2.0

O MCP Server foi refatorado com base no schema OpenAPI atual da aplicação Twenty CRM.

Principais Mudanças

Stack de Componentes

A arquitetura do projeto é composta por 3 serviços containerizados:

1. ambienz-twenty-server - Twenty CRM (porta 3000)

   • Servidor principal da aplicação CRM
   • Interface web para gestão de clientes
   • API REST integrada

2. ambienz-twenty-worker - Twenty Worker

   • Processador de jobs assíncronos
   • Automações e workflows
   • Integração com Redis

3. ambienz-twenty-mcp-server - MCP Server (porta 3001)

   • Servidor Protocol Model Context
   • Integração com IA e automações inteligentes
   • Gerenciamento de ferramentas e contexto

Base URL Atualizada

• Agora usa https://twenty.ambienz.com.br/rest por padrão
• Endpoints seguem o padrão REST do Twenty CRM

Objetos Suportados

1. People - Gestão de pessoas

   • list_people, create_person, get_person, update_person, delete_person
   • Campos atualizados: name (objeto), emails (objeto), phones (objeto), linkedinLink, xLink

2. Companies - Gestão de empresas

   • list_companies, create_company, get_company, update_company, delete_company
   • Campos brasileiros: cnpj, razaoSocial

3. Opportunities - Gestão de oportunidades

   • list_opportunities, create_opportunity, get_opportunity, update_opportunity, delete_opportunity
   • Campos: amount (objeto), closeDate, stage, companyId, pointOfContactId

4. Notes - Gestão de notas

   • list_notes, create_note, get_note, update_note, delete_note
   • Campos: title, body, position

5. Tasks - Gestão de tarefas

   • list_tasks, create_task, get_task, update_task, delete_task
   • Campos: title, body, dueAt, status, assigneeId

6. Conversas - Objeto customizado

   • list_conversas, create_conversa, get_conversa, update_conversa, delete_conversa
   • Campos: name, conversasId, agent, lead

7. Faturas - Objeto customizado

   • list_faturas, create_fatura, get_fatura, update_fatura, delete_fatura
   • Campos: name, status

Paginação e Filtros

Todos os endpoints de listagem agora suportam:

• filter - Query JSON para filtros
• orderBy - Ordenação por campo
• limit - Limite de resultados (max 100)
• depth - Profundidade de relações
• startingAfter / endingBefore - Cursores de paginação

Uso

# Configurar variáveis de ambiente
export TWENTY_API_KEY="your-api-key"
export TWENTY_BASE_URL="https://twenty.ambienz.com.br/rest"
export PORT=3000

# Executar servidor
node mcp/index.js

Deployment com Docker Compose

Para deployar a stack completa localmente:

# Copiar arquivo de ambiente
cp .env.example .env

# Iniciar todos os serviços
docker-compose up -d

# Verificar status
docker-compose ps

# Ver logs
docker-compose logs -f ambienz-twenty-mcp-server

O serviço Twenty CRM estará disponível na URL configurada (ex: https://twenty.ambienz.com.br) e o MCP Server na porta 3001.

Endpoints

• GET /health - Health check
• POST /tools/:toolName - Executar ferramenta específica
• POST /mcp - Endpoint MCP via Server-Sent Events