Ploomes MCP Server

Servidor MCP (Model Context Protocol) que conecta asistentes de IA al CRM Ploomes. Expone 153 herramientas que cubren el CRUD de las entidades de Ploomes, configuración de embudos y campos, CPQ (modelos de Propuesta/Venta/Documento), automatizaciones y webhooks. Historial de cambios en CHANGELOG.md.

Configuración

uv sync

Cree un .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

Ejecute el servidor:

uv run python ploomes_server.py

Related MCP server: Kommo MCP Server

Verificación

Antes de subir el servidor o abrir un PR, ejecute la verificación estática (no usa red ni credenciales):

uv run python tests/verificar_tools.py --strict

Detecta nombres de herramientas duplicados, archivos con una herramienta no registrada en tools/__init__.py e importación de un símbolo inexistente — los tres problemas que la consolidación del 29/07/2026 encontró. En tiempo de ejecución, register_all_tools también lanza RuntimeError si dos archivos declaran el mismo nombre de herramienta, en lugar de dejar que FastMCP descarte uno de ellos silenciosamente. Guion de prueba manual contra una cuenta de sandbox (nunca producción):

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

Generación de HTML de modelo de propuesta

En Ploomes no existe un editor de campo de formulario separado del HTML: los campos que el usuario rellena al generar una propuesta son derivados por el backend a partir del parseo del HTML del cuerpo del documento (Pages[].BodySourceCode). Escribir el HTML con las etiquetas correctas es la única forma de declarar un campo. Hay dos caminos, y ambos terminan en salvar_modelo_proposta: Nativo — solo necesita la PLOOMES_API_KEY. El agente escribe el HTML.

1. guia_html_modelo_proposta — devuelve las convenciones de marcado.

2. El agente escribe el HTML, con <field key="..."> para campos nativos y <newfield .../> donde necesite un campo personalizado.

3. criar_campos_novos_llm — crea los campos personalizados y devuelve las Keys.

4. aplicar_campos_novos_html_llm — intercambia los <newfield> por los <field key="...">.

5. salvar_modelo_proposta — crea el modelo y la primera página.

6. montar_bloco_produtos_proposta — inserta el bloque de ítems, si lo hay. Gateway — requiere PLOOMES_AI_CLIENT_ID/SECRET, y acepta PDF, Word e imagen como referencia (el camino nativo depende de que el agente lea los archivos por su cuenta).

7. gerar_modelo_html_ia → 2. identificar_campos_html_ia →

8. criar_campos_em_massa_ia → 4. aplicar_campos_no_html_ia →

9. salvar_modelo_proposta Atajo — para un modelo simple que ya tenga la identidad visual del cliente, montar_modelo_proposta_com_identidade hace todo en una sola llamada, a partir de un brief de marca ya extraído. Use los pasos individuales cuando necesite un layout a medida o retomar desde un error a mitad de camino.

Las convenciones de marcado provienen de ingeniería inversa y captura de red de la app, no de documentación oficial de Ploomes. Valide en sandbox antes de producción.

Añadir a 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"
      }
    }
  }
}

Depuración con LangSmith

Con las variables LANGSMITH_* definidas, las llamadas a herramientas se trazan automáticamente. Ejecute uv run python example.py y vea el dashboard en https://smith.langchain.com