Ploomes MCP Server

Ploomes CRM에 AI 어시스턴트를 연결하는 MCP(Model Context Protocol) 서버입니다.
Ploomes 엔티티의 CRUD, 퍼널 및 필드 구성, CPQ(제안/판매/문서 템플릿), 자동화와 웹훅을 포함한 153개 도구를 제공합니다.
변경 이력은 CHANGELOG.md에 있습니다.

Setup

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

Verificação

서버를 배포하거나 PR을 열기 전에 정적 검증을 실행하세요(네트워크나 자격 증명을 사용하지 않음):

uv run python tests/verificar_tools.py --strict

이 검증은 중복된 도구 이름, tools/__init__.py에 등록되지 않은 도구가 있는 파일, 존재하지 않는 심볼의 import를 감지합니다 — 29/07/2026의 통합 작업에서 발견된 세 가지 문제입니다. 런타임에서 register_all_tools는 두 파일이 동일한 도구 이름을 선언하면 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과 별도의 양식 필드 편집기가 없습니다. 사용자가 제안을 생성할 때 입력하는 필드는 문서 본문(Pages[].BodySourceCode) HTML을 파싱하여 백엔드에서 파생됩니다. 올바른 태그로 HTML을 작성하는 것만이 필드를 선언할 수 있는 유일한 방법입니다.

두 가지 경로가 있으며 두 경로 모두 salvar_modelo_proposta로 끝납니다:
네이티브 — PLOOMES_API_KEY만 있으면 됩니다. 에이전트가 HTML을 작성합니다.

1. guia_html_modelo_proposta — 마크업 규칙을 반환합니다.

2. 에이전트가 HTML을 작성합니다. 네이티브 필드에는 <field key="...">를, 사용자 지정 필드가 필요하면 <newfield .../>를 사용합니다.

3. criar_campos_novos_llm — 사용자 지정 필드를 생성하고 Keys를 반환합니다.

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가 브랜드 브리프를 바탕으로 한 번에 모든 작업을 처리합니다. 맞춤형 레이아웃이 필요하거나 작업 중간의 오류를 이어서야 할 때는 개별 단계를 사용하세요.

마크업 규칙은 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에서 대시보드를 확인하세요.