MCP Pipedrive Server

Servidor MCP em TypeScript para a API da Pipedrive. As ferramentas são agrupadas por recurso (deals, persons, activities, etc.) e aceitam caminhos dinâmicos para que o LLM monte qualquer endpoint a partir da especificação oficial.

• Base da API: https://api.pipedrive.com/v1
• Especificações OpenAPI:
  • v1: https://developers.pipedrive.com/docs/api/v1/openapi.yaml
  • v2: https://developers.pipedrive.com/docs/api/v1/openapi-v2.yaml
• Guia oficial: https://pipedrive.readme.io/docs/getting-started (pode ser aberto via MCP Playwright para navegação guiada)

Instalação

npm install
npm run build

Configuração

Defina seu token em .env (ou variável de ambiente):

PIPEDRIVE_API_TOKEN=8780bdfa0875417cb100ddf6396769b5c28ba0a4
# Opcional: sobrescreva a base (ex.: sandbox ou proxy)
# PIPEDRIVE_API_BASE_URL=https://api.pipedrive.com/v1

O token acima segue o formato fornecido e pode ser usado para testes de listagem.

Como funciona

Cada ferramenta tem um nome pipedrive-{recurso} e constrói a rota a partir de:

• Base geral: https://api.pipedrive.com/v1
• Base do recurso (exemplos abaixo)
• path: parte restante montada pela IA. Ex.: "", "123", "123/activities", "search".
• query: parâmetros de busca/filtro (term, start, limit, filter_id etc.).
• body: JSON para POST/PUT/PATCH.

Recursos e exemplos rápidos

| Tool | Base | Exemplos de path | | --- | --- | --- | | pipedrive-deals | /deals | "" (lista), "123", "search" (usa query.term), "summary" | | pipedrive-persons | /persons | "", "123", "search", "collection" | | pipedrive-activities | /activities | "", "123", "collection" | | pipedrive-activityTypes | /activityTypes | "", "123" | | pipedrive-organizations | /organizations | "", "123", "search", "collection" | | pipedrive-leads | /leads | "", "123", "archived", "search" | | pipedrive-notes | /notes | "", "123" | | pipedrive-products | /products | "", "123", "search" | | pipedrive-pipelines | /pipelines | "", "123", "123/deals" | | pipedrive-stages | /stages | "", "123", "123/deals" | | pipedrive-users | /users | "", "me", "find", "123" | | pipedrive-files | /files | "", "remote", "remoteLink" |

Exemplos de chamada

Listar deals (5 primeiros):

{
  "name": "pipedrive-deals",
  "arguments": {
    "method": "GET",
    "path": "",
    "query": { "start": 0, "limit": 5 }
  }
}

Buscar pessoa por termo:

{
  "name": "pipedrive-persons",
  "arguments": {
    "method": "GET",
    "path": "search",
    "query": { "term": "Alice", "limit": 3 }
  }
}

Criar atividade:

{
  "name": "pipedrive-activities",
  "arguments": {
    "method": "POST",
    "body": {
      "subject": "Follow-up demo",
      "type": "call",
      "due_date": "2025-12-01",
      "deal_id": 1
    }
  }
}

Em qualquer chamada, ajuste path para incluir IDs e sub-rotas conforme a OpenAPI.

Uso no Claude Code

Adicione o servidor via stdio (exemplo):

claude mcp add pipedrive --command "node /home/marcelo/developer/mcp/mcp-pipedrive/dist/index.js"

Depois de conectado, solicite: “Liste os primeiros deals usando o tool pipedrive-deals com method: GET e query.limit: 3”.

Uso no Codex (CLI)

Configure no arquivo de MCP da Codex CLI, apontando para o comando de stdio:

{
  "name": "pipedrive",
  "command": "node",
  "args": ["/home/marcelo/developer/mcp/mcp-pipedrive/dist/index.js"],
  "env": {
    "PIPEDRIVE_API_TOKEN": "8780bdfa0875417cb100ddf6396769b5c28ba0a4"
  }
}

Peça algo como: “Use o tool pipedrive-users com method: GET e path: \"me\" para trazer meus dados”.

Uso via pacote publicado no NPM

Instale o pacote (local ao projeto da IDE ou global):

npm install @marcelocorrea/mcp-pipedrive
# ou
npm install -g @marcelocorrea/mcp-pipedrive

Depois aponte Claude Code ou Codex para o binário Node do pacote:

{
  "name": "pipedrive",
  "command": "node",
  "args": ["./node_modules/@marcelocorrea/mcp-pipedrive/dist/index.js"],
  "env": {
    "PIPEDRIVE_API_TOKEN": "SEU_TOKEN",
    "PIPEDRIVE_AUTH_MODE": "both"
  }
}

Se instalar globalmente, ajuste args para o caminho global (ex.: $(npm root -g)/@marcelocorrea/mcp-pipedrive/dist/index.js).

Uso direto com npx

Sem instalar nada, chame via npx (usa o binário mcp-pipedrive):

"mcp-pipedrive": {
  "command": "npx",
  "args": [
    "--yes",
    "@marcelocorrea/mcp-pipedrive",
    "--transport",
    "stdio"
  ],
  "env": {
    "PIPEDRIVE_API_TOKEN": "SEU_TOKEN",
    "PIPEDRIVE_AUTH_MODE": "both"
  }
}

Desenvolvimento

• npm run dev para rodar via tsx (hot-reload).
• npm run build para gerar dist/.
• npm run start para executar o build.
• Pronto para publicar no NPM (files: ["dist"]).

Notas

• Autenticação via Authorization: Bearer {PIPEDRIVE_API_TOKEN}.
• path é sempre relativo ao base path do recurso; combine segmentos livremente.
• Autenticação: por padrão envia Authorization: Bearer e ?api_token=. Para trocar, defina PIPEDRIVE_AUTH_MODE como header, query ou both (default).
• Para inspeção visual, abra a documentação oficial com o MCP Playwright e consulte os endpoints no OpenAPI.