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 完整開發教學

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）

本プロジェクトは3つの MCP トランスポートモードをサポートしています：

モード	説明	適用シナリオ
`stdio`	標準入出力（デフォルト）	Claude Desktop、Cursor IDE、ローカル開発
`http`	HTTP プロトコル	リモートサービス、n8n、Web アプリ統合
`sse`	Server-Sent Events（非推奨）	旧版クライアントとの下位互換性

stdio vs HTTP/SSE：計算リソースの場所

両モードの重要な違いは、「誰が MCP Server を起動するか」および「計算リソースがどこで実行されるか」です：

stdio モード（ローカル計算）

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

クライアント（Claude Desktop など）が MCP Server をサブプロセスとして起動
MCP Server があなたのコンピュータの CPU/RAM を使用
サーバーはクライアントの起動/終了に合わせて動作

HTTP/SSE モード（リモート計算）

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

MCP 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

クライアント設定(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 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

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

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

{
  "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 で削除を実行する必要があります。

ヘルスチェック

HTTP/SSE トランスポートモードでは /health エンドポイントを提供します：

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

Docker ヘルスチェック、Kubernetes プローブ、ロードバランサーの生存確認に適しています。stdio モードでは影響しません。

License

Apache 2.0

odoo19-mcp-server