Odoo Assistant MCP Server

Виртуальный сотрудник Odoo через Model Context Protocol (MCP). Этот сервер предоставляет LLM бизнес-логику, записи и рабочие процессы Odoo, позволяя безопасно запрашивать, создавать, обновлять и выполнять действия с данными Odoo.

Быстрый старт

1. Установка

Запустите сервер напрямую:

uvx odoo-assistant

Или установите его в своё окружение:

uv pip install odoo-assistant

Установка из исходного кода для разработки также возможна:

uv pip install git+https://github.com/singleflo/odoo-assistant-mcp

2. Настройка переменных окружения

Требуются две переменные; всё остальное определяется автоматически или имеет значение по умолчанию:

• ODOO_BASE_URL: Базовый URL вашего экземпляра Odoo (например, https://mycompany.odoo.com).

• ODOO_API_KEY: API-ключ Odoo (Odoo 14+, создаётся в Настройки > Пользователи > API-ключи > Новый). Пароль от учётной записи не принимается: ключ привязан к пользователю, имеет ограниченную область действия и может быть отозван отдельно.

Дополнительная настройка:

• ODOO_DB: Имя базы данных. Определяется автоматически, если экземпляр обслуживает только одну базу; обязательно, если их несколько — в сообщении об ошибке будут перечислены все.

• ODOO_USER: Логин. Определяется по ключу ценой до 59 дополнительных запросов; определение не удастся, если uid владельца ключа равен 60 или выше. Указание логина избавляет от проверки.

• ODOO_MCP_MAX_LEVEL: Максимальный уровень безопасности, который может выполнять этот сервер, от 0 до 4 (по умолчанию: 3). С помощью этого параметра вы делаете сервер только для чтения или разрешаете удаление — см. Выбор предельного уровня.

• ODOO_MCP_PROTECTED_HOSTS: Разделённые запятыми хосты, на которые этот сервер отказывается записывать (по умолчанию пусто — ни один хост не встроен в пакет). Указанный хост всё равно разрешает чтение; для записи требуется ODOO_ALLOW_PROD_WRITE=yes как осознанное переопределение.

Related MCP server: mcp-server-odoo

Уровень безопасности

Каждая запись и действие проходят через динамический классификатор безопасности перед тем, как попасть в Odoo. Операции классифицируются по уровням от L0 до L5:

Выбор предельного уровня

ODOO_MCP_MAX_LEVEL задаёт максимальный уровень, который может выполнять этот сервер. Каждое значение является накопительным — оно разрешает свой уровень и всё, что ниже:

Стоит знать два поведения перед выбором числа:

• 5 не открывает L5. Оба варианта L5 отклоняются до того, как уровень вообще считывается. L5_PRIVATE отклоняется, потому что Odoo сам отвергает любой метод, начинающийся с _, так что никакой предельный уровень не сможет его разрешить; L5_UNKNOWN отклоняется, потому что метод, не классифицированный никем, по определению имеет непроверенные последствия. Способ разрешить такой метод — добавить его в WRITE_L1/L3/L4 в safety_layer.py — в коде, с проверкой, а не через конфигурацию.

• Недопустимое значение приводит к ошибке при запуске. ODOO_MCP_MAX_LEVEL="O" вызывает ошибку, а не откат к значению по умолчанию, потому что значение по умолчанию допускает запись: опечатка не должна дать вам сервер для записи, который вы считали только для чтения.

Предельный уровень задаётся вне канала связи, человеком, и считывается из окружения процесса при запуске. Модель, работающая с этим сервером, не может его повысить; когда вызов превышает предельный уровень, в отказе указывается требуемый уровень, чтобы агент мог объяснить, что изменит операция, и оставить решение за вами.

Обратите внимание, что это полномочия данного сервера, а не учётной записи. Агент с доступом к оболочке всегда может обойти MCP-сервер, вызвав Odoo напрямую. Ограничение, которое должно действовать независимо от клиента, относится к правам доступа Odoo пользователя, которому принадлежит API-ключ, — там его обеспечивает сервер Odoo.

Поддержка версий Odoo

Odoo 14.0 — абсолютный минимум поддерживаемой версии, так как этот сервер аутентифицируется только с помощью API-ключей, которых нет в Odoo 13 и более ранних.

Путь создания API-ключа

Чтобы создать API-ключ, войдите в свой экземпляр Odoo и перейдите по адресу: Настройки / Мой профиль → Безопасность учётной записи → Новый API-ключ

Примечание о транспорте и устаревании

Клиент автоматически определяет, доступен ли нативный API JSON-2 по адресу /json/2/<model>/<method> (использующий Authorization: bearer <API_KEY>), и в противном случае переключается на XML-RPC. Обратите внимание, что XML-RPC и JSON-RPC объявлены устаревшими в Odoo 19 и запланированы к удалению в Odoo 22.

Источники

• Odoo 14.0 External API Documentation (введение в API-ключи)

• Odoo 19.0 External API Documentation (JSON-2)

• Odoo 19.0 External RPC API Documentation (устаревание XML-RPC)

• Odoo Standard & Extended Support Policy (сроки поддержки)

Инструменты и ресурсы

Сервер предоставляет 19 инструментов и 2 типа ресурсов:

Инструменты

1. search_read: Поиск и чтение записей одним вызовом (Odoo search_read).

2. read_record: Чтение одной записи по id, всегда с указанными полями.

3. count_records: Подсчёт записей, соответствующих домену (Odoo search_count).

4. instance_overview: Сводка подключённого экземпляра: версия, компании, объёмы по областям, внутренние модули, аномалии.

5. required_fields: Список того, что Odoo требует перед create для модели, значение по умолчанию, которое он применил бы, и как существующие записи фактически его используют.

6. create_record: Создание записи с повторным использованием существующего совпадения, если задан unique_on.

7. write_record: Запись значений полей в одну запись и отчёт о том, что фактически изменилось.

8. run_action: Запуск метода рабочего процесса и отчёт о состоянии, в котором он оставил запись.

9. cancel_record: Отмена записи через action_cancel с последующим выполнением возвращаемого мастера.

10. notify_user: Уведомление пользователей в чате записи. По умолчанию внутреннее.

11. create_activity: Планирование действия: единственное уведомление, которое содержит срок.

12. download_docs: Сохранение всех документов записи на диск, включая файлы из чата.

13. generate_pdf: Генерация PDF записи и возврат места сохранения.

14. list_message_targets: Список тех, кому можно отправить сообщение, и где — внутренние пользователи с присутствием (онлайн/отошёл/офлайн) и открытые беседы вызывающего. Спрашивайте это перед отправкой.

15. read_conversation: Чтение беседы Discuss, сначала новые.

16. send_direct_message: Отправка личного сообщения Discuss, которое появляется в системном трее чата пользователя в реальном времени — без электронной почты, достигает его независимо от настройки уведомлений.

17. send_channel_message: Публикация в существующем канале Discuss; отказ, если в комнате есть не-сотрудник.

18. explore_module: Изучение структуры модуля путём опроса живого экземпляра.

19. list_known_modules: Список модулей, которые изучил этот сервер: имя, дата генерации, записи.

Инструменты 10-11 (notify_user, create_activity) уведомляют О записи и попадают в колокольчик Входящие; инструменты 14-17 — это беседы Discuss, которые попадают в системный трей чата. «Отправить сообщение пользователю X» — это второй тип: send_direct_message, а не notify_user.

Ресурсы

• odoo://skill: Доступ к инструкциям навыка ассистента Odoo.

• odoo://ref/*: Доступ к сгенерированной справочной документации по изученным модулям.

Примеры конфигурации хостов

Каждый пример ниже содержит только то, что важно: две обязательные переменные и предельный уровень — единственный параметр, определяющий, может ли этот сервер писать, и указанный в файле, которым владеет человек. База данных и логин определяются автоматически, а 3 — значение по умолчанию для предельного уровня. Обратите внимание на кавычки: значения окружения — строки.

Claude Desktop

Добавьте это в ваш claude_desktop_config.json:

{
  "mcpServers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_MCP_MAX_LEVEL": "3"
      }
    }
  }
}

Cursor

Добавьте это в ваш .cursor/mcp.json или настройте в интерфейсе настроек Cursor:

{
  "mcpServers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_MCP_MAX_LEVEL": "3"
      }
    }
  }
}

VS Code Copilot

Добавьте это в ваш settings.json VS Code:

{
  "mcp.servers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_MCP_MAX_LEVEL": "3"
      }
    }
  }
}

opencode

Добавьте это в opencode.json или .opencode/opencode.json в вашем проекте, или в ~/.config/opencode/opencode.json, чтобы сделать сервер доступным везде:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "odoo-assistant": {
      "type": "local",
      "enabled": true,
      "command": [
        "uvx",
        "odoo-assistant"
      ],
      "timeout": 120000,
      "environment": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_MCP_MAX_LEVEL": "3"
      }
    }
  }
}

Структура opencode отличается от указанных выше хостов в том, что он отвергает: ключ — mcp (не mcpServers), требуется type, command — это один массив, содержащий программу и её аргументы (отдельного args нет), а блок окружения — environment (не env).

Установите timeout осознанно. По умолчанию он равен 5000 мс, а первый вызов сессии включает аутентификацию плюс, для instance_overview, десятки XML-RPC запросов — что с комфортом превышает пять секунд на реальном экземпляре.

opencode считывает свою конфигурацию один раз при запуске и не перезагружает её «на лету», поэтому после редактирования закройте и перезапустите. Любые изменения, внесённые сюда — включая предельный уровень — вступят в силу только при следующем запуске.

ChatGPT (Пользовательские коннекторы)

Чтобы подключить этот сервер к ChatGPT через Пользовательские коннекторы:

1. Перейдите в Настройки → Коннекторы → Добавить коннектор.

2. Введите URL сервера или выберите из Реестра.

3. Введите учетные данные Odoo при появлении запроса.

Hermes

Добавьте сервер с помощью Hermes CLI:

hermes mcp add odoo-assistant \
  --env ODOO_BASE_URL=https://mycompany.odoo.com \
  --env ODOO_API_KEY=your-api-key-here \
  --env ODOO_MCP_MAX_LEVEL=3 \
  --args run odoo-assistant

В примерах опущены необязательные переменные. Установите ODOO_DB, если экземпляр обслуживает несколько баз данных, ODOO_USER, чтобы пропустить проверку uid, и ODOO_MCP_MAX_LEVEL, чтобы изменить максимальный уровень с его значения по умолчанию 3.

Лицензия

Этот проект лицензирован под лицензией MIT. Подробности см. в файле LICENSE.