odoo19-mcp-server

odoo19-mcp-server

MCP Server for Odoo 19 using JSON-2 API, built with FastMCP

Category
访问服务器

README

Odoo 19 MCP Server (JSON-2 API)

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

特性 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

<details> <summary><b>手動設定 JSON（加到 ~/.claude.json）</b></summary>

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

</details>

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

<details> <summary><b>手動設定 JSON</b></summary>

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

</details>

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

<details> <summary><b>手動設定 JSON</b></summary>

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

</details>

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

<details> <summary><b>手動設定 JSON</b></summary>

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

</details>

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

<details> <summary><b>手動設定 JSON</b></summary>

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

</details>

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

<details> <summary><b>手動設定 JSON（加到 ~/.gemini/settings.json）</b></summary>

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

</details>

安全機制

唯讀模式

設定 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

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具，连接你所有喜爱的工具：Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器，集成了 Kagi 搜索功能和 Claude AI，使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议（MCP）服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选