Ploomes MCP Server

MCP-сервер (Model Context Protocol), который подключает ИИ-ассистентов к CRM Ploomes. Предоставляет 153 инструмента, охватывающих CRUD сущностей Ploomes, настройку воронок и полей, CPQ (модели предложений/продаж/документов), автоматизации и вебхуки. История изменений в 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. Во время выполнения register_all_tools также вызывает RuntimeError, если два файла объявляют одно и то же имя инструмента, вместо того чтобы позволить FastMCP молча отбросить один из них. Сценарий ручного тестирования на 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 с правильными тегами — единственный способ объявить поле. Есть два пути, и оба заканчиваются на 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 — вставляет блок элементов, если он есть. Gateway — требует 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