Ploomes MCP Server

MCP-Server (Model Context Protocol), der KI-Assistenten mit dem CRM Ploomes verbindet. Er stellt 153 Tools bereit, die CRUD der Ploomes-Entitäten, Konfiguration von Funnels und Feldern, CPQ (Angebots-, Verkaufs- und Dokumentvorlagen), Automatisierungen und Webhooks abdecken. Änderungshistorie in CHANGELOG.md.

Einrichtung

uv sync

Erstelle eine .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

Starte den Server:

uv run python ploomes_server.py

Related MCP server: Kommo MCP Server

Überprüfung

Bevor Sie den Server starten oder einen PR öffnen, führen Sie die statische Überprüfung aus (verwendet weder Netzwerk noch Anmeldedaten):

uv run python tests/verificar_tools.py --strict

Sie erkennt doppelte Tool-Namen, Dateien mit nicht in tools/__init__.py registrierten Tools und Importe nicht existierender Symbole – die drei Probleme, die die Konsolidierung vom 29.07.2026 gefunden hat. Zur Laufzeit wirft register_all_tools außerdem einen RuntimeError, wenn zwei Dateien denselben Tool-Namen deklarieren, anstatt dass FastMCP eines davon stillschweigend verwirft. Manueller Testplan gegen ein Sandbox-Konto (niemals Produktion):

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

Generierung von HTML für Angebotsvorlagen

In Ploomes gibt es keinen vom HTML getrennten Formularfeld-Editor: Die Felder, die der Benutzer beim Erstellen eines Angebots ausfüllt, werden vom Backend abgeleitet, indem das HTML des Dokumentkörpers geparst wird (Pages[].BodySourceCode). Das HTML mit den richtigen Tags zu schreiben ist die einzige Möglichkeit, ein Feld zu deklarieren. Es gibt zwei Wege, und beide enden bei salvar_modelo_proposta: Nativ – benötigt nur den PLOOMES_API_KEY. Der Agent schreibt das HTML.

1. guia_html_modelo_proposta — gibt die Markierungskonventionen zurück.

2. Der Agent schreibt das HTML, mit <field key="..."> für native Felder und <newfield .../> wo ein benutzerdefiniertes Feld benötigt wird.

3. criar_campos_novos_llm — erstellt die benutzerdefinierten Felder und gibt die Keys zurück.

4. aplicar_campos_novos_html_llm — ersetzt die <newfield> durch die <field key="...">.

5. salvar_modelo_proposta — erstellt das Modell und die erste Seite.

6. montar_bloco_produtos_proposta — fügt den Artikelblock ein, falls vorhanden. Gateway – erfordert PLOOMES_AI_CLIENT_ID/SECRET und akzeptiert PDF, Word und Bilder als Referenz (der native Weg hängt davon ab, dass der Agent die Dateien selbst liest).

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 Abkürzung – für ein einfaches Modell mit bereits vorhandener visueller Identität des Kunden erledigt montar_modelo_proposta_com_identidade alles in einem Aufruf, ausgehend von einem bereits extrahierten Marken-Brief. Verwenden Sie die einzelnen Schritte, wenn Sie ein maßgeschneidertes Layout benötigen oder von einem Fehler in der Mitte fortsetzen möchten.

Die Markierungskonventionen stammen aus Reverse Engineering und Netzwerkabfang der App, nicht aus offizieller Ploomes-Dokumentation. Validieren Sie in der Sandbox, bevor Sie in Produktion gehen.

Hinzufügen zu 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 mit LangSmith

Mit den definierten Variablen LANGSMITH_* werden Tool-Aufrufe automatisch getracet. Führen Sie uv run python example.py aus und sehen Sie das Dashboard unter https://smith.langchain.com.