Odoo 18 Server

License: Apache-2.0 Python

Odoo 18 MCP Server，使用 JSON-RPC API 連線。

Based on twtrubiks/odoo19-mcp-server, adapted for Odoo 18.

技術棧

• Python: 3.13
• FastMCP: >=3.0.0,<4.0.0
• odoo-client-lib: 2.0.1 (使用 jsonrpc/jsonrpcs protocol)

架構

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/>jsonrpc/jsonrpcs protocol]
    end

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

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

與 Odoo 19 版本的差異

環境變數

建立 .env 檔案：

cp .env.example .env
# 編輯 .env 填入你的 API Key

如何取得 API Key

推薦：使用 Setup Wizard（bash setup-hr.sh），全自動完成。

手動方式：

1. 登入 Odoo
2. 點擊右上角頭像 → 我的個人資料（My Profile）
3. 切換到 帳號安全（Account Security） 頁籤
4. 找到 API Keys 區塊，點擊 New API Key
5. 輸入描述（例如 MCP Server），點擊確認
6. 複製產生的 API Key，貼到 .env 的 ODOO_API_KEY 欄位

注意：API Key 只會顯示一次，請妥善保存。API Key 的權限等同於該用戶帳號的權限。

快速設定（Setup Wizard）

HR 等非技術人員只需執行一個指令：

bash setup-hr.sh

Wizard 會自動：

1. 安裝 Python 虛擬環境和依賴
2. 開啟瀏覽器選擇環境（SIT / PRD）
3. 導到 Odoo 登入頁（SAML/SSO 自動登入）
4. 點擊「Connect Claude Code」一鍵產生 API Key
5. 自動寫入 .env 並註冊 MCP Server

前提：Odoo 上需安裝 mcp_api_key 模組（見下方）。

Odoo 模組：mcp_api_key

odoo_addons/mcp_api_key/ 提供 /mcp/setup 頁面，讓 SAML/SSO 用戶一鍵產生 API Key。

安裝方式：將 mcp_api_key/ 複製到 Odoo addons 路徑，然後在 Odoo 後台安裝「MCP API Key Generator」。

部署設定：建立 deploy-config.json（已在 .gitignore 中）：

{
  "environments": {
    "sit": {"name": "SIT (Testing)", "odoo_url": "https://your-sit.com/", "database": "sit-db"},
    "prd": {"name": "Production", "odoo_url": "https://your-prd.com/", "database": "prd-db"}
  },
  "defaults": {"readonly_mode": true, "view_filtered_mode": true}
}

手動安裝

pip install -r requirements.txt

啟動方式

開發模式（MCP Inspector）

fastmcp dev inspector odoo_mcp_server.py

傳輸模式（Transport）

啟動不同模式

# 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

MCP Resources

MCP Tools

Claude Code MCP 設定

本機執行

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

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

Docker

claude mcp add odoo-mcp-server -- docker run -i --rm \
  -e ODOO_URL=https://your-odoo-server.com/ \
  -e ODOO_DATABASE=your_database_name \
  -e [email protected] \
  -e ODOO_API_KEY=your_api_key_here \
  -e READONLY_MODE=true \
  -e VIEW_FILTERED_MODE=true \
  odoo18-mcp-server

雲端部署（HTTP 模式）

Docker Compose 範例：

services:
  odoo-mcp:
    build: .
    ports:
      - "8000:8000"
    environment:
      - ODOO_URL=https://your-odoo-server.com/
      - ODOO_DATABASE=your_database_name
      - [email protected]
      - ODOO_API_KEY=your_api_key_here
      - READONLY_MODE=true
      - VIEW_FILTERED_MODE=true
    command: ["python", "odoo_mcp_server.py", "--transport", "http", "--host", "0.0.0.0", "--port", "8000"]
    restart: unless-stopped

Client 設定：

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

Docker 建置

docker build -t odoo18-mcp-server .

安全機制

唯讀模式

設定 READONLY_MODE=true 啟用唯讀模式，適用於生產環境查詢：

• 寫入工具（create_record、update_record、delete_record、execute_method）透過 FastMCP tags 直接隱藏，LLM 不會看到這些工具

View 欄位過濾模式（本專案新增）

設定 VIEW_FILTERED_MODE=true 啟用，適用於讓非技術人員（如 HR）安全使用 MCP 查詢 PRD 資料。

問題：Odoo 的 ORM API 會回傳用戶有權限的所有欄位，即使 UI 上沒有顯示（例如薪資、個資等）。

解決方案：透過 get_views() 取得 list + form view 定義，只回傳 view 中可見的欄位。

一般模式:  search_records("hr.employee") → 209 個欄位（含薪資、個資）
View 過濾: search_records("hr.employee") → 138 個欄位（只有 view 上顯示的）

運作方式：

1. 首次查詢某個 model 時，呼叫 get_views() 一次取得 list + form view
2. 從 models 回傳取得該用戶可見的欄位定義（已過濾 groups）
3. 從 arch XML 解析 <field> 名稱作為補充
4. 合併欄位集合並快取，所有讀取操作只回傳這些欄位
5. 即使 LLM 嘗試指定不在 view 中的欄位，也會被過濾掉

建議 HR 使用的設定（.env）：

ODOO_URL=https://your-odoo-server.com/
ODOO_DATABASE=your_database_name
[email protected]
ODOO_API_KEY=hr_user_api_key_here
READONLY_MODE=true          # 禁止寫入
VIEW_FILTERED_MODE=true     # 只看 view 可見欄位

刪除二次確認

delete_record 內建 confirm 機制，LLM 必須先以 confirm=False 呼叫取得確認提示，經使用者同意後才能以 confirm=True 執行刪除。

健康檢查

HTTP/SSE transport 模式下提供 /health 端點：

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

測試

pip install -r requirements-dev.txt
pytest tests/

Credits

Based on twtrubiks/odoo19-mcp-server by @twtrubiks.

License

Apache 2.0