Skip to main content
Glama
deenesjakoptruzh
thalleshcm

Ploomes MCP Server

by thalleshcm
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Ploomes MCP Server

MCP（模型上下文协议）服务器，将AI助手连接到Ploomes CRM。暴露153个工具，涵盖Ploomes实体的CRUD、漏斗和字段配置、CPQ（提案/销售/文档模板）、自动化和Webhooks。变更历史见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中未注册的工具文件，以及导入不存在的符号——这是2026年7月29日整合时发现的三个问题。在运行时，register_all_tools也会在两个文件声明相同工具名称时抛出RuntimeError，而不是让FastMCP静默丢弃其中一个。针对沙盒账户的手动测试脚本（绝不要用生产环境）：

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是声明字段的唯一方式。有两条路径，两条都以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官方文档。在生产环境前请在沙盒中验证。

添加到 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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Kommo MCP Server

    wdavidce
    F
    license
    B
    quality
    D
    maintenance
    Enables AI assistants to autonomously interact with Kommo CRM, providing tools for managing pipelines, leads, contacts, and custom fields via the Kommo API v4.
    27
    1
    -

  • Ploomes MCP Server

    victorbenazzi
    A
    license
    A
    quality
    D
    maintenance
    Connects AI agents to the Ploomes CRM REST API, exposing 56 tools for managing contacts, deals, tasks, pipelines, interactions, quotes, orders, products, fields, users, and account information.
    56
    8 npm
    1
    MIT