@agasalhem/pipedrive-mcp

MCP server stdio que expõe a API inteira do Pipedrive (v1 + v2) pro Claude, via padrão search + execute. Reaproveitável entre clientes: o que muda é só o token por conta.

Instalação

Via npx (recomendado — zero instalação)

Adicione ao .mcp.json do seu projeto:

{
  "mcpServers": {
    "pipedrive": {
      "command": "npx",
      "args": ["-y", "@agasalhem/pipedrive-mcp"],
      "env": {
        "PIPEDRIVE_API_TOKEN": "seu-token-aqui"
      }
    }
  }
}

O token fica em Settings → Personal preferences → API no Pipedrive.

Via npm global

npm install -g @agasalhem/pipedrive-mcp

E no .mcp.json:

{
  "mcpServers": {
    "pipedrive": {
      "command": "pipedrive-mcp",
      "env": {
        "PIPEDRIVE_API_TOKEN": "seu-token-aqui"
      }
    }
  }
}

Variáveis de ambiente

| Variável | Obrigatória | Descrição | |---|---|---| | PIPEDRIVE_API_TOKEN | sim | Token da API do Pipedrive | | PIPEDRIVE_BASE_URL | não | Substitui só o domínio (ex: https://suaempresa.pipedrive.com) |

Como funciona

A API do Pipedrive tem ~370 operações. Registrar uma tool por endpoint estouraria o contexto do Claude, então o catálogo fica interno e o server expõe só três tools:

• search_actions — acha a operação por intenção em linguagem natural (PT ou EN). Retorna o ID, método, rota, qual tool de execução usar e os schemas de path/query/body. Chamar isto primeiro.
• execute_read_action — executa uma operação de leitura (GET). Marcada readOnlyHint, então o Claude Code pode auto-aprovar.
• execute_write_action — executa escrita (POST/PUT/PATCH/DELETE). Marcada destructiveHint, então pede confirmação antes de alterar o CRM.

Separar leitura de escrita é a regra de annotations do MCP e dá uma UX de permissão mais segura num CRM em produção.

Por que dois specs (v1 + v2)

O Pipedrive migrou o CRUD central (deals, persons, organizations, activities, products) pra API v2 e tirou do spec v1. O v1 guarda a cauda longa (fields, followers, participants, filters, pipelines, stages, notes, leads). O catálogo mescla os dois e, em colisão de operationId, o v2 vence. Cada ação carrega seu próprio server porque as bases diferem (/v1 vs /api/v2).

Ranking da busca

Keyword scoring com alguns ajustes pra qualidade: peso maior no primeiro termo da intenção, bônus quando a entidade bate com o recurso raiz da rota, mapa de verbo→método (criar→POST, atualizar→PATCH, etc.) e dicionário de sinônimos PT→EN (negócio→deal, pessoa→person, atividade→activity...). Não é semântico/embeddings, mas acerta a operação central no topo na maioria das intenções comuns de RevOps.

Desenvolvimento

npm install
npm run build      # gera o catálogo a partir dos specs e compila

npm run fetch-specs   # rebaixa os OpenAPI v1 e v2 do Pipedrive
npm run build         # regenera o catálogo e recompila

Os specs ficam versionados em openapi/. Rodar fetch-specs quando o Pipedrive publicar mudanças na API.

Teste manual

# lista as tools
npx @modelcontextprotocol/inspector --cli node dist/server.js --method tools/list

# busca (não precisa de token)
npx @modelcontextprotocol/inspector --cli node dist/server.js \
  --method tools/call --tool-name search_actions --tool-arg intent="criar um negócio"

Estrutura

openapi/          specs v1 e v2 do Pipedrive (versionados)
scripts/          gerador do catálogo (mescla os specs)
data/catalog.json catálogo enxuto consumido em runtime
src/catalog.ts    tipos, carregamento e ranking
src/client.ts     client HTTP (auth x-api-token, base por versão)
src/server.ts     server stdio + as três tools

Notas

• O token nunca aparece na URL retornada pro Claude (auth vai no header).
• Respostas grandes são truncadas em 60k caracteres com aviso pra paginar.
• Read/write split: leitura auto-aprovável, escrita pede confirmação.

Licença

MIT