Conexa

→ Como funciona o Conexa MCP — a página do projeto, com o sistema explicado visualmente.

Conecte o Claude (ou qualquer assistente de IA compatível com MCP) ao seu sistema Conexa.

Depois de instalado, você pode simplesmente conversar com a IA:

"Liste as cobranças em aberto deste mês" "Cadastre o cliente João da Silva, CPF 123.456.789-00" "Quais salas estão reservadas para amanhã?" "Crie uma venda do produto X para o cliente Y"

São 83 ferramentas cobrindo toda a API v2 do Conexa: vendas, clientes, pessoas, planos, contratos, vendas recorrentes, produtos, cobranças, despesas, fornecedores, campos extras, centros de custo, contas, unidades, reservas de sala, check-in/check-out e mais.

🚀 Instalação com ajuda da IA (recomendado)

Não precisa entender de programação. Copie o bloco abaixo e cole em uma conversa com o Claude (Claude Code, Claude Desktop ou outro agente de IA que consiga executar comandos no seu computador). Ele verifica os pré-requisitos, oferece pilotar o navegador na etapa do token e só declara pronto depois de validar a conexão de verdade.

Pré-requisitos: Node.js 18+ · um cliente MCP (Claude Code ou Claude Desktop) · acesso de administrador ao seu Conexa.

Quero instalar o servidor MCP do Conexa (https://github.com/Expert-Integrado/conexa-mcp) nesta máquina. Conduza o processo do início ao fim, nesta ordem, sem pular a validação final:

1. PRÉ-REQUISITOS — verifique com comandos reais: rode "node --version" (precisa ser 18 ou superior). Se o Node.js não estiver instalado, me oriente a instalar pelo site https://nodejs.org e só continue depois de confirmar. Identifique também qual cliente estou usando (Claude Code, Claude Desktop ou outro cliente MCP).

2. SUBDOMÍNIO — me pergunte o subdomínio do meu Conexa: é a primeira parte do endereço que uso para acessar o sistema (se acesso "minhaempresa.conexa.app", o subdomínio é "minhaempresa"). Não continue sem essa resposta.

3. TOKEN DE APLICAÇÃO (etapa de navegador) — o token é criado dentro do Conexa, no menu Config > Integrações > API / Token, por um usuário administrador. Antes de executar, pergunte com a ferramenta AskUserQuestion (botões; se o cliente não tiver botões, pergunte em texto): "Essa etapa é no navegador. Quer que eu faça para você?" com estas opções:
   - "Sim, pilote o navegador" (opção padrão): use o Playwright MCP; se ele não estiver instalado, instale antes com "claude mcp add playwright -- npx -y @playwright/mcp@latest" e me avise caso precise reiniciar a sessão. Abra https://SUBDOMINIO.conexa.app, PARE na tela de login e peça para eu fazer o login sozinho — NUNCA peça minha senha no chat. Depois que eu confirmar que entrei, navegue até Config > Integrações > API / Token e me ajude a gerar e copiar o Token de Aplicação.
   - "Usar o Claude in Chrome": mesmo roteiro, pilotando o meu Chrome (que já tem minha sessão logada).
   - "Prefiro fazer manualmente": me passe o passo a passo — acessar https://SUBDOMINIO.conexa.app com usuário administrador, abrir Config > Integrações > API / Token, gerar o token e colar aqui UMA única vez, só para ele ir direto para o arquivo de configuração local.

4. REGISTRO DO MCP — configure o servidor com as variáveis de ambiente corretas:
   - Claude Code: claude mcp add conexa --scope user --env CONEXA_SUBDOMAIN=<subdominio> --env CONEXA_TOKEN=<token> -- npx -y conexa-mcp
   - Claude Desktop: adicione ao claude_desktop_config.json (menu Configurações > Desenvolvedor > Editar configuração) o servidor "conexa" com command "npx", args ["-y", "conexa-mcp"] e as variáveis CONEXA_SUBDOMAIN e CONEXA_TOKEN.
   - Outro cliente MCP: configuração equivalente (command: npx -y conexa-mcp + as duas variáveis).

5. SEGURANÇA — o token vive SOMENTE no arquivo de configuração local do MCP (ou em um .env local). Não repita o token na conversa depois de salvo, não grave em outros arquivos e nunca envie para a internet ou para um repositório.

6. VALIDAÇÃO REAL — peça para eu reiniciar o cliente (fechar e abrir) e então chame a ferramenta test_connection do servidor conexa. Só considere a credencial válida se a resposta confirmar que a conexão está funcionando. Se der erro, leia a mensagem (token errado, subdomínio errado e token expirado são as causas mais comuns) e me ajude a corrigir antes de seguir.

7. TESTE FINAL E RESUMO — faça uma chamada de leitura de verdade (por exemplo, list_companies com limit 1), me mostre o resultado e termine com um resumo: o que foi instalado, onde o token ficou salvo e 3 exemplos de pedidos que eu já posso fazer.

O que você vai precisar ter em mãos

Guia detalhado passo a passo — incluindo Claude Desktop, execução a partir do código-fonte e solução de problemas: INSTALL.md.

🔧 Instalação manual

claude mcp add conexa --scope user \
  --env CONEXA_SUBDOMAIN=minhaempresa \
  --env CONEXA_TOKEN=seu_token_aqui \
  -- npx -y conexa-mcp

{
  "mcpServers": {
    "conexa": {
      "command": "npx",
      "args": ["-y", "conexa-mcp"],
      "env": {
        "CONEXA_SUBDOMAIN": "minhaempresa",
        "CONEXA_TOKEN": "seu_token_aqui"
      }
    }
  }
}

git clone https://github.com/Expert-Integrado/conexa-mcp.git
cd conexa-mcp
npm install
npm run build

Variáveis de ambiente

* Informe CONEXA_SUBDOMAIN ou CONEXA_BASE_URL · ** Informe CONEXA_TOKEN ou usuário e senha.

🔒 Segurança

• O token nunca sai do seu computador: fica apenas no arquivo de configuração local do seu cliente MCP e é enviado somente para o seu próprio Conexa (https://SEUSUBDOMINIO.conexa.app).
• Nada de credenciais no código, em logs ou neste repositório.
• O servidor respeita o limite oficial de 60 requisições/minuto da API (com espera automática) e tenta novamente sozinho quando o limite é atingido.
• Ferramentas de exclusão/encerramento são marcadas como destrutivas — clientes como o Claude pedem sua confirmação antes de executá-las.

🧰 Ferramentas disponíveis

Uma ferramenta para cada endpoint da API v2 do Conexa, organizadas por área:

Observações:

• A rota POST /auth da API não vira ferramenta: o próprio servidor a utiliza internamente quando você configura usuário/senha.
• Listagens usam paginação (limit/offset) e aceitam os filtros documentados pela API (ex.: customerId, status, datas). Filtros de múltiplos valores aceitam vírgula: "450,216".
• Webhooks do Conexa estão fora do escopo deste servidor (webhooks exigem um serviço recebendo chamadas na internet, não um servidor local).

👩‍💻 Para desenvolvedores

npm install        # dependências
npm run generate   # regenera src/endpoints.ts a partir de spec/postman-collection.json
npm run build      # compila TypeScript para dist/
npm test           # smoke test (handshake MCP + contagem de tools via stdio)

As definições das 82 ferramentas de API são geradas automaticamente da collection Postman oficial (spec/postman-collection.json). Quando a Conexa atualizar a documentação, basta baixar a collection nova e rodar npm run generate.

Licença

MIT