Ploomes MCP Server

MCP server (Model Context Protocol) that connects AI assistants to the Ploomes CRM. It exposes 153 tools covering CRUD of Ploomes entities, funnel and field configuration, CPQ (Proposal/Sale/Document templates), automations, and webhooks. Change history in CHANGELOG.md.

Setup

uv sync

Create a .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

Run the server:

uv run python ploomes_server.py

Related MCP server: Kommo MCP Server

Verification

Before starting the server or opening a PR, run the static verification (it does not use network or credentials):

uv run python tests/verificar_tools.py --strict

It detects duplicate tool names, a file with a tool not registered in tools/__init__.py, and imports of nonexistent symbols — the three problems that the 29/07/2026 consolidation found. At runtime, register_all_tools also raises RuntimeError if two files declare the same tool name, instead of letting FastMCP silently discard one of them. Manual test script against a sandbox account (never production):

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

Proposal template HTML generation

In Ploomes there is no form field editor separate from the HTML: the fields the user fills in when generating a proposal are derived by the backend from parsing the HTML of the document body (Pages[].BodySourceCode). Writing the HTML with the right tags is the only way to declare a field. There are two paths, and both end in salvar_modelo_proposta: Native — only needs the PLOOMES_API_KEY. The agent writes the HTML.

1. guia_html_modelo_proposta — returns the markup conventions.

2. The agent writes the HTML, with <field key="..."> for native fields and <newfield .../> where a custom field is needed.

3. criar_campos_novos_llm — creates the custom fields and returns the Keys.

4. aplicar_campos_novos_html_llm — replaces the <newfield> with <field key="...">.

5. salvar_modelo_proposta — creates the template and the first page.

6. montar_bloco_produtos_proposta — inserts the items block, if any. Gateway — requires PLOOMES_AI_CLIENT_ID/SECRET, and accepts PDF, Word, and image as reference (the native path depends on the agent reading the files on its own).

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 Shortcut — for a simple template already with the client's visual identity, montar_modelo_proposta_com_identidade does everything in one call, from an already extracted brand brief. Use the individual steps when you need a custom layout or to resume from an error in the middle.

The markup conventions come from reverse engineering and network capture of the app, not from official Ploomes documentation. Validate in sandbox before production.

Add to 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 with LangSmith

With the LANGSMITH_* variables set, tool calls are traced automatically. Run uv run python example.py and see the dashboard at https://smith.langchain.com