Pipedrive MCP Server

MCP (Model Context Protocol) server para integracao com o CRM Pipedrive. Permite que assistentes AI (Claude Code, Claude Desktop, etc.) interajam diretamente com o Pipedrive.

Funciona com qualquer conta do Pipedrive — cada usuario configura seu proprio token e sincroniza seus campos e tipos de atividade automaticamente.

Credenciais sao pessoais. Cada pessoa usa seu proprio token de API do Pipedrive. Nenhuma credencial esta incluida neste repositorio.

Funcionalidades

• Negocios: listar, buscar, criar, atualizar, resumo, historico, fluxo de movimentacoes

• Contatos: listar, buscar, criar, atualizar

• Organizacoes: buscar, criar, detalhes

• Atividades: listar, criar, atualizar, com aliases e duracoes padrao configuraveis

• Notas: criar, editar, listar por negocio

• Produtos: listar, vincular a negocios

• Campos personalizados: sincronizacao automatica, listar, atualizar com protecao contra sobrescrita

• Tipos de atividade: sincronizacao automatica, aliases configuraveis, duracoes padrao por tipo

• Pipeline/Etapas: listar pipelines e etapas

• Paginacao: suporte a start/limit em todos os endpoints de listagem + buscar_todos para deals

• Dominio dinamico: links de resposta usam o dominio da sua conta automaticamente

• Fuso horario: conversao automatica de horarios (configuravel via variavel de ambiente)

• Visibilidade: deals, contatos e organizacoes criados visiveis para toda a empresa

Instalacao

git clone https://github.com/ericluciano/pipedrive-mcp.git
cd pipedrive-mcp
npm install

Configuracao

Cada usuario deve configurar seu proprio token da API do Pipedrive.

1. Obter o token

Acesse: Pipedrive > Configuracoes > Dados pessoais > API e copie seu token pessoal.

2. Configurar no Claude Code / Claude Desktop

Adicione ao seu arquivo de configuracao MCP (claude_desktop_config.json ou equivalente):

{
  "mcpServers": {
    "pipedrive": {
      "command": "node",
      "args": ["/caminho/para/pipedrive-mcp/index.js"],
      "env": {
        "PIPEDRIVE_API_KEY": "seu_token_aqui",
        "PIPEDRIVE_TIMEZONE": "America/Sao_Paulo"
      }
    }
  }
}

3. Configurar via variavel de ambiente (alternativa)

cp .env.example .env
# Edite .env e coloque seu token e timezone

4. Onboarding guiado

Apos configurar o token, peca ao Claude para iniciar o onboarding:

"Inicie o onboarding do Pipedrive MCP"

O onboarding guia voce por 3 passos:

1. Sincronizar dados — executa sync_fields (campos personalizados) e sync_activity_types (tipos de atividade)

2. Mostrar sua estrutura — exibe campos, pipelines, etapas e tipos de atividade com aliases

3. Configurar regras de negocio — voce explica suas regras e o Claude gera o CLAUDE.md

Pronto! O MCP esta configurado e pronto para uso.

Campos personalizados

Cada conta do Pipedrive tem campos personalizados diferentes (com hashes e IDs unicos). O sync_fields resolve isso automaticamente.

Como funciona

1. sync_fields — busca todos os campos personalizados da sua conta via API e gera o arquivo fields.js local

2. get_deal — traduz os hashes internos para nomes legiveis (ex: cb145b... vira "Segmento")

3. create_deal / update_deal_fields — aceita nomes legiveis e converte para o formato da API

4. list_deal_fields — lista todos os campos disponiveis com suas opcoes

Quando resincronizar

Execute sync_fields novamente quando:

• Criar novos campos personalizados no Pipedrive

• Alterar opcoes de campos enum/set

• Renomear campos existentes

Protecao contra sobrescrita

Ao atualizar campos com update_deal_fields, campos que ja tem valor preenchido nao sao sobrescritos por padrao. O MCP retorna os conflitos para confirmacao. Use force: true somente apos confirmacao explicita.

Tipos de atividade

Cada empresa tem tipos de atividade diferentes no Pipedrive. O MCP se adapta automaticamente a qualquer configuracao.

Como funciona

1. sync_activity_types — busca os tipos da sua conta e gera activity_types.js local

2. O MCP aceita key da API, nome ou alias ao criar/atualizar atividades

3. Duracoes padrao podem ser configuradas por tipo

Aliases

Voce pode configurar nomes alternativos para cada tipo de atividade. Por exemplo, o tipo call (key da API) pode ter os aliases ligacao, chamada, telefone. Quando alguem diz "crie uma ligacao", o MCP resolve automaticamente para o tipo correto.

Duracoes padrao

Cada tipo pode ter uma duracao padrao. Se voce configura call com duracao de 15 minutos, toda ligacao criada sem especificar duracao tera 15 minutos automaticamente.

Configurando aliases e duracoes

Apos rodar sync_activity_types, edite o arquivo activity_types.js gerado:

export const ACTIVITY_TYPES = {
  "call": {
    "name": "Chamada",
    "aliases": ["ligacao", "chamada"],     // adicione aliases aqui
    "default_duration": 15,                 // duracao em minutos
    "is_custom": false,
    "active": true
  }
};

Ou peca ao Claude:

"Configure o tipo call com alias ligacao e duracao 15 minutos"

Quando resincronizar

Execute sync_activity_types novamente quando:

• Criar novos tipos de atividade no Pipedrive

• Renomear tipos existentes

• Ativar/desativar tipos

Importante: O re-sync preserva aliases e duracoes que voce configurou. Apenas os dados da API (nome, status) sao atualizados.

Arquivos de configuracao por conta

O MCP gera arquivos locais especificos da sua conta. Esses arquivos nao sobem para o GitHub (estao no .gitignore).

Paginacao

Todos os endpoints de listagem suportam paginacao:

- limit: quantidade por pagina (padrao 100, max 500)
- start: offset (padrao 0)

O retorno inclui metadados de paginacao:

{
  "dados": [...],
  "paginacao": {
    "inicio": 0,
    "total_nesta_pagina": 100,
    "mais_itens": true,
    "proximo_inicio": 100
  }
}

Para buscar todos os deals automaticamente, use buscar_todos: true (max 5000 registros).

Regras de negocio (CLAUDE.md)

O MCP cuida da parte tecnica (comunicacao com a API). Para que o agente AI siga as regras do seu processo comercial, voce precisa configurar um arquivo CLAUDE.md com suas regras de negocio.

O que incluir no CLAUDE.md

• Etapas do pipeline com criterios de movimentacao

• Campos obrigatorios por etapa

• Motivos de perda e regras de reativacao

• Produtos/servicos com precos e regras comerciais

• Tipos de atividade com aliases e duracoes

• ICP (Perfil Ideal do Cliente)

• Regras de comportamento do agente (criar deal, mover, perder, etc.)

Como usar

1. Copie o template CLAUDE.md.example incluido neste repositorio

2. Preencha com as regras especificas da sua empresa

3. Configure como:

   • Claude Code: salve como CLAUDE.md na raiz do projeto ou em ~/.claude/CLAUDE.md

   • Claude Desktop / Cloud Coworking: adicione como arquivo de memoria/contexto

Seguranca

• O token nunca e commitado no repositorio (.env esta no .gitignore)

• fields.js e activity_types.js (dados da conta) tambem estao no .gitignore

• Operacoes DELETE sao bloqueadas por padrao

• Campos com valor existente nao sao sobrescritos sem confirmacao explicita (force: true)

• Dominio da empresa e detectado automaticamente via API (sem hardcode)

• Contatos e organizacoes criados com visibilidade para toda a empresa (visible_to: 3)

Guardrails anti-duplicata (v5.6.0)

Regras de protecao embutidas no MCP (nao dependem de configuracao do usuario):

Por que ultimos 8 digitos? O padrao de busca por telefone usa apenas os 8 ultimos digitos para tolerar erros de DDD e o 9o digito adicionado em numeros WhatsApp brasileiros.

Ferramentas disponiveis (34 tools)

Configuracao

Negocios

Contatos

Organizacoes

Atividades

Notas

Produtos

Estrutura