Ploomes MCP Server

MCP（Model Context Protocol）サーバーで、AI アシスタントを Ploomes CRM に接続します。Ploomes エンティティの CRUD、ファネルとフィールドの設定、CPQ（提案/販売/文書テンプレート）、自動化、Webhook をカバーする 153 のツールを公開しています。変更履歴は CHANGELOG.md にあります。

セットアップ

uv sync

.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

サーバーを実行してください：

uv run python ploomes_server.py

Related MCP server: Kommo MCP Server

検証

サーバーを起動する前、または PR を開く前に、静的検証を実行してください（ネットワークも資格情報も使用しません）：

uv run python tests/verificar_tools.py --strict

重複したツール名、tools/__init__.py に登録されていないツールを含むファイル、存在しないシンボルのインポートを検出します。これらは 29/07/2026 の統合で見つかった 3 つの問題です。実行時には、register_all_tools も、2 つのファイルが同じツール名を宣言した場合、FastMCP が一方を黙って破棄するのではなく、RuntimeError を発生させます。 sandbox アカウントに対する手動テストの手順（本番環境は不可）：

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

提案テンプレートの HTML 生成

Ploomes には HTML とは別のフォームフィールドエディタはありません。ユーザーが提案を生成する際に入力するフィールドは、ドキュメント本文の HTML（Pages[].BodySourceCode）のパースから バックエンドによって導出されます。HTML を正しいタグで記述することだけが、フィールドを宣言する唯一の方法です。 2 つの方法があり、どちらも salvar_modelo_proposta で終わります： ネイティブ — PLOOMES_API_KEY のみが必要です。エージェントが HTML を記述します。

1. guia_html_modelo_proposta — マークアップの規約を返します。

2. エージェントが HTML を記述します。ネイティブフィールドには <field key="...">、カスタムフィールドが必要な場所には <newfield .../> を使用します。

3. criar_campos_novos_llm — カスタムフィールドを作成し、キーを返します。

4. aplicar_campos_novos_html_llm — <newfield> を <field key="..."> に置き換えます。

5. salvar_modelo_proposta — テンプレートと最初のページを作成します。

6. montar_bloco_produtos_proposta — 項目ブロックがあれば挿入します。 ゲートウェイ — PLOOMES_AI_CLIENT_ID/SECRET が必要で、参照として PDF、Word、画像を受け付けます（ネイティブの方法では、エージェントが自分でファイルを読む必要があります）。

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 ショートカット — クライアントのビジュアルアイデンティティを備えたシンプルなテンプレートの場合、montar_modelo_proposta_com_identidade は、すでに抽出されたブランドブリーフから 1 回の呼び出しですべてを実行します。カスタムレイアウトが必要な場合や、途中のエラーから再開する場合は、個別の手順を使用してください。

マークアップの規約は、Ploomes の公式ドキュメントではなく、アプリのリバースエンジニアリングとネットワークキャプチャによるものです。本番の前に sandbox で検証してください。

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"
      }
    }
  }
}

LangSmith でのデバッグ

LANGSMITH_* 変数が定義されていると、ツール呼び出しは自動的にトレースされます。uv run python example.py を実行し、https://smith.langchain.com でダッシュボードを確認してください。