Ploomes MCP Server

Servidor MCP (Model Context Protocol) que conecta assistentes de IA ao CRM Ploomes. Expõe 153 tools cobrindo CRUD das entidades do Ploomes, configuração de funis e campos, CPQ (modelos de Proposta/Venda/Documento), automações e webhooks.

Histórico de mudanças em CHANGELOG.md.

Setup

uv sync

Crie um .env:

# Obrigatórias
PLOOMES_API_KEY=sua_chave
PLOOMES_BASE_URL=https://api2.ploomes.com
PLOOMES_USER_ID=id_numerico

# Opcional — loga request/response completo no stderr
PLOOMES_DEBUG=1

# Opcional — apenas para o caminho "gateway" de geração de HTML de proposta
# (gerar_modelo_html_ia, identificar_campos_html_ia, criar_campos_em_massa_ia).
# É uma credencial PRÓPRIA dessa feature, diferente da PLOOMES_API_KEY.
# Sem ela, essas três tools retornam erro explicativo e o resto do servidor
# funciona normalmente — veja "Geração de HTML" abaixo para a alternativa que
# não precisa de credencial extra.
PLOOMES_AI_CLIENT_ID=
PLOOMES_AI_CLIENT_SECRET=
PLOOMES_AI_BASE_URL=https://ai.ploomes.run/api

# Opcional — debugging com LangSmith
OPENAI_API_KEY=
LANGSMITH_TRACING=true
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
LANGSMITH_API_KEY=
LANGSMITH_PROJECT=ploomes-mcp

Rode o servidor:

uv run python ploomes_server.py

Verificação

Antes de subir o servidor ou abrir um PR, rode a verificação estática (não usa rede nem credenciais):

uv run python tests/verificar_tools.py --strict

Ela detecta nome de tool duplicado, arquivo com tool não registrada em tools/__init__.py, e import de símbolo inexistente — os três problemas que a consolidação de 29/07/2026 encontrou. Em runtime, register_all_tools também levanta RuntimeError se dois arquivos declararem o mesmo nome de tool, em vez de deixar o FastMCP descartar um deles silenciosamente.

Roteiro de teste manual contra uma conta de sandbox (nunca produção):

uv run python test_novas_tools.py --etapa 1   # só leitura
uv run python test_novas_tools.py --etapa 2   # escrita, pede confirmação

Geração de HTML de modelo de proposta

No Ploomes não existe editor de campo de formulário separado do HTML: os campos que o usuário preenche ao gerar uma proposta são derivados pelo backend a partir do parsing do HTML do corpo do documento (Pages[].BodySourceCode). Escrever o HTML com as tags certas é a única forma de declarar um campo.

Há dois caminhos, e os dois terminam em salvar_modelo_proposta:

Nativo — só precisa da PLOOMES_API_KEY. O agente escreve o HTML.

1. guia_html_modelo_proposta — devolve as convenções de marcação.
2. O agente escreve o HTML, com <field key="..."> para campos nativos e <newfield .../> onde precisar de campo customizado.
3. criar_campos_novos_llm — cria os campos customizados e devolve as Keys.
4. aplicar_campos_novos_html_llm — troca os <newfield> pelos <field key="...">.
5. salvar_modelo_proposta — cria o modelo e a primeira página.
6. montar_bloco_produtos_proposta — insere o bloco de itens, se houver.

Gateway — exige PLOOMES_AI_CLIENT_ID/SECRET, e aceita PDF, Word e imagem como referência (o caminho nativo depende do agente ler os arquivos por conta própria).

1. gerar_modelo_html_ia → 2. identificar_campos_html_ia →
2. criar_campos_em_massa_ia → 4. aplicar_campos_no_html_ia →
3. salvar_modelo_proposta

Atalho — para um modelo simples já com a identidade visual do cliente, montar_modelo_proposta_com_identidade faz tudo numa chamada, a partir de um brief de marca já extraído. Use os passos individuais quando precisar de layout sob medida ou retomar de um erro no meio.

As convenções de marcação vêm de engenharia reversa e captura de rede do app, não de documentação oficial da Ploomes. Valide em sandbox antes de produção.

Add ao Claude Desktop / Cursor

{
  "mcpServers": {
    "ploomes": {
      "command": "uv",
      "args": ["run", "python", "/caminho/para/ploomes_server.py"],
      "env": {
        "PLOOMES_API_KEY": "sua_chave",
        "PLOOMES_BASE_URL": "https://api2.ploomes.com",
        "PLOOMES_USER_ID": "id_numerico"
      }
    }
  }
}

Debug com LangSmith

Com as variáveis LANGSMITH_* definidas, as chamadas de tool são tracejadas automaticamente. Rode uv run python example.py e veja o dashboard em https://smith.langchain.com