Pipedrive MCP: consultar e alterar o CRM por nível de segurança

Para quem

Se queres consultar, criar ou atualizar dados CRM Pipedrive diretamente no Claude Code ou Claude Desktop, este serviço encaixa. É um servidor MCP para uso local ou autoalojado, autenticado com uma chave API Pipedrive.

Para quem já tem uma conta Pipedrive e uma chave API, e cujo cliente consegue correr MCP STDIO. O texto oficial diz que o transporte atual é só STDIO, sem OAuth alojado. Se precisas de acesso HTTP remoto ou início de sessão OAuth, esta página não tem um caminho utilizável.

O nome do pacote tem de ser o @ckalima/pipedrive-mcp-server com âmbito. O texto oficial é explícito: se um fragmento antigo cita o pipedrive-mcp-server sem âmbito, esse é outro pacote sem relação; não instales o errado.

Primeira tentativa em 3 minutos

O caminho oficial recomendado é a instalação guiada. Pré-requisitos: ter uma chave API Pipedrive pronta, escolher Claude Code ou Claude Desktop, transporte só STDIO.

Num terminal executa:

npx -y @ckalima/pipedrive-mcp-server init

Segue o guia para escrever o servidor na configuração do cliente. Quando tiveres de alterar a configuração à mão, o comando é npx, os argumentos são -y e @ckalima/pipedrive-mcp-server, e define PIPEDRIVE_API_KEY no ambiente. Não escrevas nenhuma cadeia de chave de exemplo nem uses o nome de pacote sem âmbito.

Na primeira tentativa põe PIPEDRIVE_MODE em read-only. O texto oficial define este nível como só leitura; o nível predefinido safe-write já inclui escritas não destrutivas e não serve para a primeira vez.

Depois faz uma chamada de baixo risco: consultar dados CRM. O texto oficial diz que podes Query, create, and update CRM data a partir do assistente; a primeira tentativa só faz Query. O texto oficial não dá um nome de ferramenta concreto nem um tipo de objeto. Usa só ferramentas de consulta que o cliente liste para este servidor. Não inventes nomes de ferramentas que não aparecem, nem cries nem atualizes registos.

Sinal de sucesso: regressa um resultado de consulta de registos já existentes no Pipedrive, sem escrita. Se no nível atual não se virem ferramentas de escrita, encaixa no texto oficial: ferramentas fora do nível ficam escondidas e uma chamada direta é recusada.

Casos de uso

Caso 1: consulta CRM só de leitura. Põe PIPEDRIVE_MODE em read-only e consulta dados existentes. O texto oficial só chega a Query CRM data, sem objetos, filtros nem paginação. Em caso de sucesso deves ver registos existentes; não trates uma consulta como uma exportação completa.

Caso 2: criar ou atualizar registos no nível predefinido safe-write. O texto oficial diz que o nível predefinido é leitura mais escritas não destrutivas, correspondendo a create e update. Isto altera o CRM; antes da chamada, confirma que dado de negócio vais alterar. O texto oficial não dá lista de campos nem carga de exemplo. Usa só a capacidade de criar ou atualizar que o cliente mostre, e reformula o conteúdo a escrever antes de executar. Deletes, conversions e outras irreversible writes não estão neste nível; o texto oficial exige o nível full para as abrir.

Limites de uso

PIPEDRIVE_MODE tem read-only, safe-write (predefinido) e full. Ferramentas fora do nível não aparecem na lista de ferramentas e uma chamada direta é recusada. Deletes, conversions e outras irreversible writes precisam de full; não abras esse nível na primeira tentativa.

O transporte é por agora só STDIO; Streamable HTTP é só uma marca planeada e não pode ser tratado como já fornecido nesta página. A autenticação é uma chave API Pipedrive, sem OAuth alojado. A chave vive numa variável de ambiente local; consultas e escritas saem ambas para a rede até ao Pipedrive.

O texto oficial não escreve limites de ritmo nem revogação. Se uma escrita tiver sucesso, tens de a reverter tu no Pipedrive. Usar o nome de pacote sem âmbito pipedrive-mcp-server é, segundo o texto oficial, outro pacote sem relação.