Odoo 19 MCP Server (JSON-2 API)

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

Odoo 19 MCP Server，使用 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

特性	Resources	Tools
用途	提供上下文資訊	執行操作/動作
觸發	客戶端控制（如 Claude Code）	LLM 自動決定呼叫
參數	無（或 URI 參數）	有（需 LLM 生成）
類比	員工手冊（背景知識）	工具箱（按需使用）
HTTP 類比	GET（讀取）	POST/PUT/DELETE（操作）

Resources - 動態上下文，LLM 一開始就知道的背景資訊：

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

Tools - 需要時才呼叫的操作：

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

為什麼不用 Default Prompt？

方式	Default Prompt	Resource
資料來源	寫死在程式碼	即時從 Odoo 查詢
更新時機	部署時	每次連線時
換用戶登入	資訊錯誤	自動正確

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

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

結論：Resource 是「動態的上下文」，不是靜態文字。

參考：MCP Resources | MCP Tools

環境變數

變數	說明	預設值
`ODOO_URL`	Odoo 伺服器 URL	`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、Web 應用整合
`sse`	Server-Sent Events（已棄用）	向下相容舊版 Client

stdio vs HTTP/SSE：算力位置

兩種模式的關鍵差異在於「誰來啟動 MCP Server」以及「算力在哪裡執行」：

stdio 模式（本機算力）

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

Client（如 Claude Desktop）啟動 MCP Server 作為子進程
MCP Server 使用你電腦的 CPU/RAM
Server 隨 Client 啟動/關閉

HTTP/SSE 模式（遠端算力）

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

MCP Server 獨立運行在雲端/遠端主機
多個 Client 可同時連線同一個 Server
適合團隊共用、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

Client 設定(claude)改用 URL 連線：

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

手動設定 JSON（加到 `~/.claude.json`）

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

MCP Resources

URI	說明
`odoo://models`	列出所有模型
`odoo://model/{model_name}`	取得模型欄位定義
`odoo://record/{model_name}/{record_id}`	取得單筆記錄
`odoo://user`	當前登入用戶資訊
`odoo://company`	當前用戶所屬公司資訊

MCP Tools

Tool	說明	唯讀
`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

Claude Code MCP 設定

設定檔位於 ~/.claude.json：

本機執行

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

手動設定 JSON

{
  "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

手動設定 JSON

{
  "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

手動設定 JSON

{
  "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

手動設定 JSON

{
  "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 .

Gemini MCP 設定

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

手動設定 JSON（加到 `~/.gemini/settings.json`）

{
  "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 tags 直接隱藏，LLM 不會看到這些工具

刪除二次確認

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

健康檢查

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

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

適用於 Docker healthcheck、Kubernetes probe、load balancer 探活。stdio 模式下不影響。

License

Apache 2.0

Name		Name	Last commit message	Last commit date
Latest commit History 35 Commits
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
glama.json		glama.json
odoo_mcp_server.py		odoo_mcp_server.py
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Odoo 19 MCP Server (JSON-2 API)

技術棧

架構

MCP 核心概念

Resources vs Tools

為什麼不用 Default Prompt？

環境變數

安裝

啟動方式

開發模式（MCP Inspector）

傳輸模式（Transport）

stdio vs HTTP/SSE：算力位置

啟動不同模式

雲端部署（HTTP 模式）

MCP Resources

MCP Tools

Claude Code MCP 設定

本機執行

Docker（host.docker.internal）

Docker（host network）

Docker（遠端 Odoo）

Docker 建置

Gemini MCP 設定

安全機制

唯讀模式

刪除二次確認

健康檢查

License

About

Uh oh!

Releases 1

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Odoo 19 MCP Server (JSON-2 API)

技術棧

架構

MCP 核心概念

Resources vs Tools

為什麼不用 Default Prompt？

環境變數

安裝

啟動方式

開發模式（MCP Inspector）

傳輸模式（Transport）

stdio vs HTTP/SSE：算力位置

啟動不同模式

雲端部署（HTTP 模式）

MCP Resources

MCP Tools

Claude Code MCP 設定

本機執行

Docker（host.docker.internal）

Docker（host network）

Docker（遠端 Odoo）

Docker 建置

Gemini MCP 設定

安全機制

唯讀模式

刪除二次確認

健康檢查

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages