mcp-odoo-jsonrpc 0.3.0

MCP server and CLI for Odoo ERP integration via JSON-RPC (tasks & timesheets)

MCP Odoo JSON-RPC

MCP-сервер и CLI для управления задачами и трудозатратами в Odoo ERP через JSON-RPC протокол.

---

Что это?

Odoo не предоставляет публичного REST/GraphQL API. Этот инструмент использует внутренний JSON-RPC протокол веб-клиента Odoo 17 и предоставляет два способа доступа:

• mcp-odoo-server — MCP-сервер для Claude Code и других AI-ассистентов
• mcp-odoo-cli — интерактивный терминальный клиент для человека

Scope: проектные задачи + трудозатраты (timesheets). Другие модули Odoo (CRM, Sales, Inventory) пока не поддерживаются.

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

Установка

pip install mcp-odoo-jsonrpc

Авторизация

mcp-odoo-cli login --url https://odoo.example.com

Откроется браузер — войдите в Odoo. Сессия сохранится автоматически в системное хранилище (Windows Credential Manager / macOS Keychain / GNOME Keyring).

CLI

mcp-odoo-cli

MCP-сервер (для Claude Code)

{
  "mcpServers": {
    "odoo": {
      "command": "python",
      "args": ["-m", "mcp_odoo_jsonrpc"]
    }
  }
}

Docker

docker build -t mcp-odoo .

{
  "mcpServers": {
    "odoo": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "ODOO_BASE_URL",
        "-e", "ODOO_SESSION_ID",
        "-e", "ODOO_UID",
        "-e", "ODOO_COMPANY_IDS",
        "-e", "ODOO_TRUST_MODE",
        "mcp-odoo"
      ],
      "env": {
        "ODOO_BASE_URL": "https://odoo.example.com",
        "ODOO_SESSION_ID": "your_session_id",
        "ODOO_UID": "1",
        "ODOO_COMPANY_IDS": "1",
        "ODOO_TRUST_MODE": "restricted"
      }
    }
  }
}

Возможности

Задачи и трудозатраты

Инструмент	Описание
list_tasks	Получение списка задач пользователя
get_task	Детали задачи с обсуждениями и вложениями
create_task	Создание новой задачи в проекте
update_task	Обновление задачи (название, описание и пр.)
change_task_stage	Смена стадии/статуса задачи
log_timesheet	Списание трудозатрат по задаче
get_timesheets	Получение трудозатрат по задаче

Wiki (document.page)

Инструмент	Описание
list_wiki_pages	Список wiki-страниц и категорий
get_wiki_page	Содержимое страницы (с фильтром секретов)
create_wiki_page	Создание wiki-страницы в категории
search_wiki	Поиск страниц по названию

Безопасность

MCP-сервер работает в restricted mode по умолчанию — AI видит только структурные данные без корпоративного контента:

Режим	Что видит AI	Активация
restricted	ID, стадия, часы, дедлайн. Без названий и текста	По умолчанию
full	Все данные: названия, описания, сообщения	ODOO_TRUST_MODE=full

Дополнительные меры:

• Фильтр проектов: ODOO_ALLOWED_PROJECTS=99,101 — ограничить видимые проекты
• Wiki: фильтр секретов: страницы с паролями, ключами и токенами цензурируются автоматически даже в full mode (ADR-009)
• Secure credentials: session_id хранится в системном keyring, не в plaintext
• detect-secrets: pre-commit hook предотвращает случайный коммит секретов
• CLI: всегда работает в full mode (пользователь смотрит в свой терминал)

Подробнее: SECURITY.md | ADR-005: Модель безопасности

Конфигурация

Через CLI (рекомендуется)

mcp-odoo-cli login --url https://odoo.example.com

Через переменные окружения

Переменная	Обязательная	Описание
ODOO_BASE_URL	Да	Базовый URL инстанса Odoo
ODOO_SESSION_ID	Да	Значение cookie session_id
ODOO_UID	Да	ID пользователя в Odoo
ODOO_EMPLOYEE_ID	Нет	ID сотрудника (по умолчанию = UID)
ODOO_COMPANY_IDS	Да	ID компаний (через запятую)
ODOO_TRUST_MODE	Нет	restricted (по умолчанию) или full
ODOO_ALLOWED_PROJECTS	Нет	Фильтр проектов (ID через запятую)
ODOO_LANG	Нет	Язык (по умолчанию: ru_RU)
ODOO_TZ	Нет	Часовой пояс (по умолчанию: Europe/Moscow)

См. .env.example

Архитектура

Odoo ERP (JSON-RPC)
     ↑
Anti-Corruption Layer
  ├── Transport   (httpx + session_id cookie)
  ├── Protocol    (JSON-RPC envelope, specifications)
  └── Mapper  (Odoo records ↔ Domain objects)
     ↑
Service Layer (OdooTaskService)
  ├── MCP Server  (строки для AI)
  └── CLI         (rich таблицы для человека)

DDD-паттерн: Conformist + Anti-Corruption Layer. Подробнее: Context Map | Domain Model

Технологический стек

Компонент	Технология
Язык	Python 3.12+
MCP SDK	mcp v1.12+
HTTP	httpx
Модели	pydantic v2
TUI	rich
Credentials	keyring
Browser auth	playwright (dev)
Lint	ruff
CI	GitHub Actions
Odoo	17

Документация

Документ	Описание
Context Map	Архитектура и DDD-паттерны
Domain Model	14 доменных объектов
JSON-RPC Reference	9 задокументированных эндпоинтов
ADR	9 архитектурных решений
CONTRIBUTING	Как внести вклад
SECURITY	Политика безопасности

Лицензия

MIT