Pipedrive MCP

Open source, criado por Eric Luciano na Mentoria Automações Inteligentes (Expert Integrado).

O servidor se identifica no handshake MCP com uma linha de procedência; para desativar (ex.: white-label), defina EXPERT_NO_PROVENANCE=1 no ambiente.

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

Conecta o seu Pipedrive ao Claude Code. Depois de instalar, você pede coisas como "cria um deal pro cliente X", "quais atividades eu tenho hoje?", "adiciona uma nota no deal 123" — e ele faz, direto no seu Pipedrive.

create_deal_full preserva as etapas confirmadas quando uma criação fica incompleta. Informe um operation_id estável antes de começar; a retomada com o mesmo pedido executa apenas etapas pendentes e bloqueia gravações incertas. Veja estados, exemplos e limites da retomada.

A instalação é guiada pelo próprio Claude Code. Você cola um prompt e ele conduz tudo — inclusive pegando o seu token no painel do Pipedrive por você, pelo navegador (você só faz o login). Não precisa editar arquivo, não precisa mexer em terminal.

Passo 1 — Instale o que precisa

Baixe e instale (uma vez só, na sua máquina):

• Node.js 18 ou superior — baixe e clique "Avançar" até o fim. Reinicie o computador depois.
• Claude Code — o aplicativo oficial da Anthropic.

Passo 2 — Peça pro Claude Code instalar

Abra o Claude Code e cole o prompt abaixo no chat (use o botão de copiar no canto do bloco):

Você é o instalador assistido do Pipedrive MCP da Expert Integrado
(@expertintegrado/pipedrive-mcp). Conduza a instalação de ponta a
ponta, na ordem abaixo.

Regras que valem o tempo todo:
- Nunca me peça senha no chat. Login é sempre eu quem faço, no navegador.
- Nunca exiba meu token da API nas suas respostas nem em arquivos.
  O token só pode existir na configuração local do Claude (~/.claude.json).
- Não use valores de exemplo — cada dado precisa ser o real.

1. PRÉ-REQUISITOS — verifique e me mostre o resultado:
   - `node --version` precisa ser 18 ou superior. Se não tiver, me
     mande instalar em https://nodejs.org/ e pare aqui.
   - Confirme que o comando `claude` está disponível no terminal.

2. TOKEN DO PIPEDRIVE — essa etapa é no navegador. Me pergunte com
   botões (AskUserQuestion): "Essa etapa é no navegador. Quer que eu
   faça pra você?" com três opções:

   (a) "Faz pra mim" — rota padrão, via Playwright MCP. Se as tools
       do Playwright não estiverem disponíveis nesta sessão, rode
       `claude mcp add playwright -- npx -y @playwright/mcp@latest`,
       me avise que é preciso fechar e reabrir o Claude Code e colar
       este prompt de novo — na segunda passada você retoma deste
       passo. Com o Playwright funcionando: abra
       https://app.pipedrive.com, me avise pra eu fazer login sozinho
       na janela que abriu e aguarde eu confirmar. Logado, identifique
       o domínio da minha conta pela barra de endereço (o subdomínio
       antes de .pipedrive.com) e navegue até Configurações →
       Preferências pessoais → API (URL direta:
       https://MEU-DOMINIO.pipedrive.com/settings/api). Extraia o
       token da API pessoal direto da tela, sem me mostrar o valor.

   (b) "Já uso a extensão Claude in Chrome" — mesma navegação, pelo
       meu Chrome que já está logado no Pipedrive.

   (c) "Prefiro fazer manualmente" — me passe o caminho (foto de
       perfil, canto superior direito → Configurações → Preferências
       pessoais → API → copiar o token da API pessoal) e me instrua a
       rodar EU MESMO, no meu terminal, o comando do passo 3 trocando
       SEU_TOKEN pelo token copiado — assim o token não passa pelo
       chat. Quando eu disser "pronto", pule para o passo 4.

3. REGISTRO — com o token extraído da tela (rotas a/b), rode em uma
   linha só:

   claude mcp add pipedrive -s user -e PIPEDRIVE_API_KEY=TOKEN_EXTRAIDO -e PIPEDRIVE_TIMEZONE=America/Sao_Paulo -- npx -y @expertintegrado/pipedrive-mcp

   Se eu disser que estou em outro fuso horário, use o nome IANA dele
   em PIPEDRIVE_TIMEZONE.

4. VALIDAÇÃO REAL — antes de declarar qualquer sucesso, teste o token
   com chamadas reais à API, lendo o token da configuração salva e sem
   exibi-lo: GET https://api.pipedrive.com/v1/users/me e
   GET https://api.pipedrive.com/v1/deals?limit=1. Me mostre só o
   resultado: meu nome, o domínio da conta e o título de 1 deal (ou
   "conta ainda sem deals"). Se vier 401, o token está errado — volte
   ao passo 2 em vez de concluir.

5. CONTEXTO — rode `npm view @expertintegrado/pipedrive-mcp readme` e
   absorva o conteúdo internamente (não precisa me mostrar) pra me
   ajudar a usar o Pipedrive daqui pra frente.

6. ENCERRAMENTO — me dê um resumo do que foi feito e verificado, e me
   avise pra fechar e reabrir o Claude Code (o app inteiro). Diga que,
   na volta, o teste final é pedir "lista meus deals abertos no
   Pipedrive" e, funcionando, rodar uma vez "executa o sync_all do
   Pipedrive" pro MCP aprender os campos, pipelines e usuários da
   minha conta.

O Claude Code vai:

1. Conferir Node.js e o próprio CLI
2. Buscar seu token no painel do Pipedrive por você (você só faz o login) — ou te guiar na rota manual
3. Registrar o MCP com as variáveis corretas
4. Validar o token com uma chamada real antes de dizer que terminou
5. Te avisar pra reiniciar

Quando ele pedir, feche e abra o Claude Code (feche o app inteiro, não só a aba).

Passo 3 — Teste

Com o Claude Code reaberto, pergunte:

Lista os meus deals abertos no Pipedrive.

Se ele responder com os deals, tá funcionando.

Passo 4 — (Recomendado) Sincronize os dados da sua conta

Peça ao Claude Code, uma vez só:

Execute o sync_all do Pipedrive.

Isso faz o MCP aprender os campos, pipelines, etapas, tipos de atividade, motivos de perda e níveis de visibilidade da sua conta — respostas passam a usar nomes legíveis ao invés de números internos, e as regras de qualidade (abaixo) passam a validar contra a SUA conta. Se você criar campos/pipelines novos lá no Pipedrive depois, repita esse comando.

Atualizando o MCP

Quando sair versão nova, o npx pega automaticamente na próxima inicialização — não precisa fazer nada. Se quiser forçar agora, peça ao Claude Code:

Limpa o cache do npx do Pipedrive MCP (roda npm cache clean --force) e me avisa pra reiniciar o Claude Code.

Se a nova versão mudou campos ou pipelines esperados, rode sync_all de novo.

Veio da 7.x? A 8.0 recusa chamadas incompletas que antes passavam (pessoa sem telefone/email, negócio sem funil/etapa, perdido sem motivo, atividade às 00:00). A mensagem de erro diz o que faltou e lista as opções. Rode sync_all uma vez depois de atualizar.

Não funcionou?

Cole isso no Claude Code:

O MCP do Pipedrive da Expert Integrado não está funcionando. Roda /mcp pra verificar se ele tá listado, confere se o Node.js 18+ está instalado, e me ajuda a diagnosticar. Se precisar, consulta o guia em https://github.com/Expert-Integrado/pipedrive-mcp/blob/main/docs/TROUBLESHOOTING.md.

Se mesmo assim não rolar, abra uma issue contando o que aconteceu.

O que dá pra fazer

Exemplos depois de instalado:

• "Cria um deal chamado 'Empresa X - Plano Premium' pra pessoa Maria Silva"
• "Quais atividades eu tenho agendadas pra hoje?"
• "Marca uma ligação com o Pedro Santos pra amanhã às 14h"
• "Adiciona uma nota no deal 456 dizendo que o cliente pediu desconto de 10%"
• "Me mostra o histórico de movimentação do deal 789"
• "Busca todos os contatos que trabalham na empresa ABC"

Lista completa de comandos: docs/TOOLS.md

Regras de qualidade do CRM

O MCP não deixa o CRM sujar: em vez de aceitar tudo e depender de alguém lembrar a regra, a própria tool recusa o incompleto e diz o que faltou. Regras que valem em qualquer conta:

• Contato precisa de telefone OU email; telefone é normalizado (55 + DDD + número) e formato ilegível é recusado
• Negócio precisa de funil e etapa explícitos; sem título, o MCP gera Pessoa | Empresa
• Negócio perdido exige motivo — e o motivo tem que ser um dos que existem no SEU campo "Motivo da perda"
• Atividade de contato pede horário real (nunca 00:00), tipo coerente com o conteúdo (task é ação interna) e vínculo com o negócio aberto da pessoa
• Assunto padronizado: passe intencao (follow-up, retomada, proposta, cobranca...) + contexto e o MCP monta Follow-up · resposta à proposta

Regras que dependem da sua conta — só entram se o campo existir:

• Origem obrigatória ao criar contato/negócio, se a conta tiver os campos de origem (padrão: "Origem do Contato" / "Origem da Oportunidade" + campos de detalhe). A origem do contato é gravada 1x na vida e não é sobrescrita
• Unidade de Negócio pelo funil e checklist por etapa (aviso dos campos que faltam ao mover o negócio): configuráveis

Pra ajustar nomes de campo, DDI, funil → unidade e checklist, copie regras.example.js pra regras.js ao lado do config.js e edite. Sem esse arquivo, valem só as regras universais. Caso deliberado que precise passar por uma trava (ex.: influencer antes da primeira conversa) usa force: true.

Visibilidade dos registros criados: por padrão, o maior nível que a sua conta expõe (lido pelo sync_all). Pra fixar outro, defina PIPEDRIVE_VISIBLE_TO (1, 3, 5 ou 7) no ambiente do MCP.

Quer mudar seu fuso horário?

Por padrão usamos America/Sao_Paulo. Se você estiver em outro fuso, peça ao Claude Code:

No MCP do Pipedrive, troca a variável PIPEDRIVE_TIMEZONE pra America/New_York (ou o nome IANA do fuso que você usa) e reinicie.

Instalação manual (fallback)

Pegue seu token: entre no Pipedrive, clique na sua foto de perfil (canto superior direito), vá em Configurações > Preferências pessoais > API e copie o token da API pessoal (uma sequência longa de letras e números).

Cuidado: esse token dá acesso ao SEU Pipedrive. Não compartilhe, não poste em grupo, não mande por e-mail. Cada pessoa deve pegar o próprio token.

Rode no terminal (troque SEU_TOKEN pelo token copiado):

claude mcp add pipedrive -s user \
  -e PIPEDRIVE_API_KEY=SEU_TOKEN \
  -e PIPEDRIVE_TIMEZONE=America/Sao_Paulo \
  -- npx -y @expertintegrado/pipedrive-mcp

Ou, se quiser editar o arquivo de configuração manualmente, adicione ao ~/.claude.json (Claude Code, user scope) ou ao .mcp.json (Claude Code, por projeto):

{
  "mcpServers": {
    "pipedrive": {
      "command": "npx",
      "args": ["-y", "@expertintegrado/pipedrive-mcp"],
      "env": {
        "PIPEDRIVE_API_KEY": "SEU_TOKEN",
        "PIPEDRIVE_TIMEZONE": "America/Sao_Paulo"
      }
    }
  }
}

Reinicie o Claude Code depois.

Instalação alternativa (offline, Claude Desktop, contribuidor)

Se você:

• Está em ambiente sem internet (ou com proxy que bloqueia o npm registry)
• Quer usar o Claude Desktop (app de chat) em vez do Claude Code
• Vai contribuir com o código do MCP

→ Veja o guia técnico de instalação — tem os modos via ZIP download, git clone, e a configuração para Claude Desktop e outros clientes MCP.

Segurança

• Seu token fica apenas no seu computador, dentro do arquivo de configuração do Claude
• Nenhum dado é enviado pra servidor externo — o MCP roda localmente na sua máquina
• Operações de exclusão são bloqueadas por padrão
• Campos já preenchidos são protegidos contra sobrescrita acidental

Contribuindo

Quer reportar um bug, sugerir uma melhoria ou contribuir com código? Veja CONTRIBUTING.md e, para o procedimento de release, RELEASING.md.

Licença

MIT © Expert Integrado