Odoo 19 MCP Server (JSON-2 API)

odoo19-mcp-server MCP server

License: Apache-2.0 Python GitHub stars GitHub last commit Awesome MCP Servers

Youtube Tutorial - MCP Server 自己做！Odoo 19 + FastMCP 完整開發教學

MCP-сервер для Odoo 19, использующий подключение через JSON-2 API.

Данный проект разработан на основе полного руководства по использованию Odoo 19 JSON-2 API.

Скриншот выполнения

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

Python: 3.13
FastMCP: >=3.0.0,<4.0.0
odoo-client-lib: 2.0.1 (JSON-2 API)

Архитектура

flowchart TB
    subgraph Client["MCP Client"]
        CC[Claude Code]
        GC[Gemini CLI]
        MI[MCP Inspector]
    end

    subgraph Server["MCP Server (FastMCP)"]
        R[Resources<br/>odoo://models<br/>odoo://user<br/>odoo://company]
        T[Tools<br/>search_records<br/>create_record<br/>update_record]
        DI[Dependency Injection<br/>get_shared_client]
    end

    subgraph RPC["OdooJsonRpcClient"]
        OL[odoolib<br/>json2/json2s protocol]
    end

    subgraph Odoo["Odoo Server"]
        EP["/jsonrpc endpoint"]
    end

    Client -->|MCP Protocol<br/>stdio/http/sse| Server
    R --> DI
    T --> DI
    DI --> RPC
    RPC -->|HTTP/HTTPS| Odoo

Основные концепции MCP

Ресурсы (Resources) vs Инструменты (Tools)

Характеристика	Ресурсы	Инструменты
Назначение	Предоставление контекстной информации	Выполнение операций/действий
Триггер	Управление клиентом (например, Claude Code)	LLM автоматически решает, когда вызвать
Параметры	Нет (или параметры URI)	Есть (генерируются LLM)
Аналогия	Справочник сотрудника (фоновые знания)	Набор инструментов (используется по мере необходимости)
Аналогия HTTP	GET (чтение)	POST/PUT/DELETE (операции)

Ресурсы — динамический контекст, фоновая информация, которую LLM знает с самого начала:

odoo://user     → "我是誰"
odoo://company  → "我在哪間公司"
odoo://models   → "有哪些模型可用"

Инструменты — операции, вызываемые только при необходимости:

search_records(model="res.partner", domain=[...])  → 搜尋
create_record(model="sale.order", values={...})    → 建立

Почему не использовать Default Prompt?

Способ	Default Prompt	Ресурс
Источник данных	Жестко прописан в коде	Запрос к Odoo в реальном времени
Время обновления	При развертывании	При каждом подключении
Смена пользователя	Неверная информация	Автоматически корректная

# ❌ Default Prompt（寫死）
SYSTEM_PROMPT = "當前用戶: Admin"  # 換人登入就錯了

# ✅ Resource（動態）
@mcp.resource("odoo://user")
def get_current_user():
    return client.read("res.users", [uid])  # 即時查詢

Вывод: Ресурс — это «динамический контекст», а не статический текст.

См. также: MCP Resources | MCP Tools

Переменные окружения

Переменная	Описание	Значение по умолчанию
`ODOO_URL`	URL сервера Odoo	`http://localhost:8069`
`ODOO_DATABASE`	Имя базы данных	-
`ODOO_API_KEY`	Аутентификация по API Key	-
`READONLY_MODE`	Режим только для чтения (запрет записи)	`false`

Создайте файл .env:

cp .env.example .env

Установка

pip install -r requirements.txt

Способы запуска

Режим разработки (MCP Inspector)

fastmcp dev inspector odoo_mcp_server.py

Режимы передачи (Transport)

Данный проект поддерживает три режима передачи MCP:

Режим	Описание	Сценарии использования
`stdio`	Стандартный ввод/вывод (по умолчанию)	Claude Desktop, Cursor IDE, локальная разработка
`http`	Протокол HTTP	Удаленные сервисы, n8n, интеграция с веб-приложениями
`sse`	Server-Sent Events (устарело)	Обратная совместимость со старыми клиентами

stdio vs HTTP/SSE: где выполняются вычисления

Ключевое различие между двумя режимами заключается в том, «кто запускает MCP-сервер» и «где выполняются вычисления»:

Режим stdio (локальные вычисления)

┌─────────────────────────────────────┐
│            你的電腦 💻               │
│                                     │
│  Claude Desktop ──> MCP Server      │
│                     (使用本機算力)   │
└─────────────────────────────────────┘

Клиент (например, Claude Desktop) запускает MCP-сервер как дочерний процесс
MCP-сервер использует CPU/RAM вашего компьютера
Сервер запускается/завершается вместе с клиентом

Режим HTTP/SSE (удаленные вычисления)

┌──────────────┐         ┌──────────────────┐
│   你的電腦    │         │     雲端 ☁️       │
│              │         │                  │
│Claude Desktop│ ──網路──>│   MCP Server     │
│  (輕量)      │         │  (使用雲端算力)   │
└──────────────┘         └──────────────────┘

MCP-сервер работает независимо в облаке или на удаленном хосте
Несколько клиентов могут подключаться к одному серверу одновременно
Подходит для командной работы, интеграции с n8n и промышленной эксплуатации

Запуск в разных режимах

# stdio 模式（預設）
python odoo_mcp_server.py

# HTTP 模式
python odoo_mcp_server.py --transport http --host 0.0.0.0 --port 8000

# SSE 模式（已棄用，建議使用 HTTP）
python odoo_mcp_server.py --transport sse --host 0.0.0.0 --port 8000

Облачное развертывание (режим HTTP)

Пример Docker Compose:

services:
  odoo-mcp:
    build: .
    ports:
      - "8000:8000"
    environment:
      - ODOO_URL=http://odoo:8069
      - ODOO_DATABASE=odoo19
      - ODOO_API_KEY=your_api_key_here
    command: ["python", "odoo_mcp_server.py", "--transport", "http", "--host", "0.0.0.0", "--port", "8000"]
    restart: unless-stopped

Настройка клиента (claude) для использования URL-подключения:

claude mcp add --transport http odoo-mcp https://your-cloud-server.com:8000/mcp

{
  "mcpServers": {
    "odoo-mcp": {
      "type": "http",
      "url": "https://your-cloud-server.com:8000/mcp"
    }
  }
}

Ресурсы MCP

URI	Описание
`odoo://models`	Список всех моделей
`odoo://model/{model_name}`	Получение определений полей модели
`odoo://record/{model_name}/{record_id}`	Получение отдельной записи
`odoo://user`	Информация о текущем пользователе
`odoo://company`	Информация о компании текущего пользователя

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

Инструмент	Описание	Только чтение
`list_models`	Список/поиск доступных моделей	Yes
`get_fields`	Получение определений полей модели	Yes
`search_records`	Поиск записей	Yes
`count_records`	Подсчет записей	Yes
`read_records`	Чтение записи по ID	Yes
`create_record`	Создание записи	No
`update_record`	Обновление записи	No
`delete_record`	Удаление записи (требует подтверждения)	No
`execute_method`	Выполнение метода модели	Depends

Настройка MCP для Claude Code

Файл конфигурации находится в ~/.claude.json:

Локальный запуск

claude mcp add odoo-mcp-server -- python odoo_mcp_server.py

{
  "mcpServers": {
    "odoo-mcp-server": {
      "command": "/bin/python",
      "args": [
        "odoo_mcp_server.py"
      ]
    }
  }
}

Docker (host.docker.internal)

Подходит для случаев, когда Odoo запущена локально:

claude mcp add odoo-mcp-server -- docker run -i --rm --add-host=host.docker.internal:host-gateway -e ODOO_URL=http://host.docker.internal:8069 -e ODOO_DATABASE=odoo19 -e ODOO_API_KEY=your_api_key_here odoo-mcp-server

{
  "mcpServers": {
    "odoo-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--add-host=host.docker.internal:host-gateway",
        "-e",
        "ODOO_URL=http://host.docker.internal:8069",
        "-e",
        "ODOO_DATABASE=odoo19",
        "-e",
        "ODOO_API_KEY=your_api_key_here",
        "odoo-mcp-server"
      ]
    }
  }
}

Docker (host network)

Использование сетевого режима хоста:

claude mcp add odoo-mcp-server -- docker run -i --rm --network host -e ODOO_URL=http://localhost:8069 -e ODOO_DATABASE=odoo19 -e ODOO_API_KEY=your_api_key_here odoo-mcp-server

{
  "mcpServers": {
    "odoo-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network",
        "host",
        "-e",
        "ODOO_URL=http://localhost:8069",
        "-e",
        "ODOO_DATABASE=odoo19",
        "-e",
        "ODOO_API_KEY=your_api_key_here",
        "odoo-mcp-server"
      ]
    }
  }
}

Docker (удаленная Odoo)

claude mcp add odoo-mcp-server -- docker run -i --rm -e ODOO_URL=https://example.com/ -e ODOO_DATABASE=odoo19 -e ODOO_API_KEY=your_api_key_here odoo-mcp-server

{
  "mcpServers": {
    "odoo-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "ODOO_URL=https://example.com/",
        "-e",
        "ODOO_DATABASE=odoo19",
        "-e",
        "ODOO_API_KEY=your_api_key_here",
        "odoo-mcp-server"
      ]
    }
  }
}

Сборка Docker

docker build -t odoo-mcp-server .

Настройка MCP для Gemini

gemini mcp add --scope user odoo-mcp docker -- run -i --rm --add-host=host.docker.internal:host-gateway -e ODOO_URL=http://host.docker.internal:8069 -e ODOO_DATABASE=odoo19 -e ODOO_API_KEY=your_api_key_here odoo-mcp-server

{
  "mcpServers": {
    "odoo-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--add-host=host.docker.internal:host-gateway",
        "-e",
        "ODOO_URL=http://host.docker.internal:8069",
        "-e",
        "ODOO_DATABASE=odoo19",
        "-e",
        "ODOO_API_KEY=your_api_key_here",
        "odoo-mcp-server"
      ]
    }
  }
}

Механизмы безопасности

Режим «только чтение»

Установите READONLY_MODE=true для включения режима «только чтение», подходящего для производственных сред:

Инструменты записи (create_record, update_record, delete_record, execute_method) скрываются напрямую через теги FastMCP, поэтому LLM не будет их видеть.

Подтверждение удаления

delete_record имеет встроенный механизм подтверждения: LLM должна сначала вызвать его с параметром confirm=False для получения запроса на подтверждение, и только после согласия пользователя выполнить удаление с confirm=True.

Проверка работоспособности (Health Check)

В режимах HTTP/SSE предоставляется эндпоинт /health:

curl http://localhost:8000/health
# {"status": "healthy", "service": "odoo-mcp-server", "version": "1.0.0"}

Подходит для Docker healthcheck, проверок Kubernetes, балансировщиков нагрузки. В режиме stdio не используется.

Лицензия

Apache 2.0

odoo19-mcp-server