Odoo Mcp Gateway

odoo-mcp-gateway

セキュリティを最優先した、Odoo 17/18/19 対応のバージョン非依存 MCP ゲートウェイです。YAML 設定により、標準モジュールとカスタムモジュールの両方で動作します。Odoo 側のコードは一切不要です。

30 秒で始めるクイックスタート

pip install odoo-mcp-gateway

Claude Desktop の設定（claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "odoo": {
      "command": "python",
      "args": ["-m", "odoo_mcp_gateway"],
      "env": {
        "ODOO_URL": "http://localhost:8069",
        "ODOO_DB": "your_database"
      }
    }
  }
}

Claude Desktop を再起動します。任意の会話で次のようにします。

login with method "password", username "admin", credential "your_password"

接続完了です。Claude に Odoo レコードの検索、作成、更新を依頼できます。すべての呼び出しはレート制限と監査ログの対象となり、Odoo に到達する前に 2 層のセキュリティチェックを通過します。

Odoo アドオンは不要です。Python コードを書く必要もありません。 きめ細かなアクセス制御のための YAML 設定だけで使用できます（任意です。標準設定でも安全に動作します）。

v0.2.1 の新機能

• ブルートフォース攻撃対策 — ユーザー名ごと（5 回／5 分）と送信元ごと（30 回／15 分）のロックアウト
• create_record、update_record、delete_record、execute_method の dry_run モード — 実行せずに検証
• 新しいツール 2 つ：get_defaults（Odoo のデフォルト値をプレビュー）、get_onchange（フィールドの副作用をプレビュー）
• read_group の 時間単位でのグループ化：create_date:month、date:quarter など
• ブロックリストを強化：常時ブロックされるモデルが 32 個（従来は 17 個）、常時ブロックされるメソッドが 29 個（従来は 18 個）、常時ブロックされる書き込みフィールドが 10 個、常時読み取り専用のモデルが 8 個
• has_group('base.group_system') による サーバー側の管理者確認（従来は認証レスポンスを信頼）
• 認証情報ラッパーにより、repr()／トレースバック経由のパスワード漏えいを防止
• JSON-RPC の再試行は OdooSessionExpiredError の場合にのみ実行（従来は認証エラーのたびに再試行）

セキュリティ修正 21 件の全リストについては、CHANGELOG.md を参照してください。

このプロジェクトの目的

既存の Odoo MCP サーバーには、カスタムモジュールを見落とすハードコードされたモデル一覧、後回しにされるセキュリティ、必須のカスタム Odoo アドオン、単一バージョンのみへの対応といった共通の問題があります。このゲートウェイは、それらすべてを解決します。

• 2 層のセキュリティ — MCP の制限（YAML）と Odoo 組み込みの ACL（ir.model.access + ir.rule）
• YAML による設定 — モデルの制限、RBAC、フィールド単位のアクセス制御、レート制限、監査ログ
• カスタムモジュール対応 — ir.model 経由でモデルを自動検出し、YAML 設定を追加するだけで使用可能
• バージョン非依存 — バージョン別アダプターにより Odoo 17、18、19 に対応
• Odoo 側のコードは不要 — pip install と YAML 設定だけで完了。カスタムアドオンは不要
• MCP のプリミティブをすべて提供 — ツール 31 個 + リソース 6 個 + プロンプト 12 個（ほとんどのサーバーはツールしか実装していません）
• プラグインアーキテクチャ — entry_points 経由で pip インストール可能なドメインパックにより拡張可能

アーキテクチャ

MCP Client (Claude Desktop / Claude Code / HTTP)
    |  User calls login tool with Odoo credentials
    v
MCP Server (FastMCP)
    |
    |-- security_gate()    --> Rate limit + RBAC tool access + audit logging
    |-- restrictions       --> Model/method/field block lists (YAML + hardcoded)
    |-- rbac               --> Field-level filtering + write sanitization
    |
    |-- tools/             --> 31 MCP tools (auth + schema + CRUD + workflow + plugins)
    |-- resources/         --> 6 MCP resources (odoo:// URIs)
    |-- prompts/           --> 12 reusable prompt templates
    |-- plugins/           --> Entry-point plugin system (HR, Sales, Project, Helpdesk)
    |
    |  JSON-RPC / XML-RPC as authenticated user
    v
Odoo 17/18/19 (security enforced per user via ir.model.access + ir.rule)

セキュリティパイプライン

すべてのツール呼び出しとリソース呼び出しは、このパイプラインを通過します。

Request --> Rate Limit --> Authentication Check --> RBAC Tool Access
    --> Model Restriction --> Method Restriction --> Field Validation
    --> Handler Execution --> RBAC Field Filtering --> Audit Log --> Response

YAML で上書きできない、ハードコードされた安全策：

• 常にブロックされる32モデル — システム内部情報、認証／TOTP、決済トークン、添付ファイル、mail.mail、base.automation など
• 常に読み取り専用の8モデル — mail.message、mail.followers、mail.activity、discuss.channel、mail.notification、mail.compose.message、mail.alias、discuss.channel.member（全ユーザーで読み取り可能、書き込みはブロック）
• 常にブロックされる10個の書き込みフィールド — password、password_crypt、groups_id、totp_secret、signup_token/type/expiration、api_key、share、active
• 常にブロックされる29メソッド — sudo、with_user/env/context、_sql、_write、_create、name_create、load、import_data、export_data など
• execute_method でブロックされる28個のORMメソッド（フィールドレベルのチェックを回避できないようにします）
• ユーザー名ごとのブルートフォースロックアウト — 5回失敗すると5分間ロックアウト（固定時間で、延長できません）
• 接続元ごとのブルートフォースロックアウト — 15分間に30回失敗するとロックアウトし、ユーザー名をローテーションする攻撃を防ぎます
• 認証情報のラッパークラス — パスワードは情報漏えいを防ぐ __repr__／__str__ で保存され、終了時に消去されます
• サーバー側での管理者確認 — has_group('base.group_system') が、認証レスポンスの is_admin より優先されます

クイックスタート

pip install odoo-mcp-gateway

# Copy and edit config files
cp config/restrictions.yaml.example config/restrictions.yaml
cp config/model_access.yaml.example config/model_access.yaml
cp config/rbac.yaml.example config/rbac.yaml

# Set environment variables
export ODOO_URL=http://localhost:8069
export ODOO_DB=mydb

# Run (stdio mode for Claude Desktop / Claude Code)
python -m odoo_mcp_gateway

# Or HTTP mode for web clients
MCP_TRANSPORT=streamable-http python -m odoo_mcp_gateway

Claude Desktop の設定

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "odoo": {
      "command": "python",
      "args": ["-m", "odoo_mcp_gateway"],
      "env": {
        "ODOO_URL": "http://localhost:8069",
        "ODOO_DB": "mydb"
      }
    }
  }
}

Claude Code の設定

# Add as MCP server
claude mcp add odoo -- python -m odoo_mcp_gateway

環境変数

変数	デフォルト値	説明
ODOO_URL	http://localhost:8069	Odoo サーバーの URL
ODOO_DB	(必須)	Odoo データベース名
MCP_TRANSPORT	stdio	トランスポートモード（stdio または streamable-http）
MCP_HOST	127.0.0.1	HTTP ホスト（streamable-http モード）
MCP_PORT	8080	HTTP ポート（streamable-http モード）
MCP_LOG_LEVEL	INFO	ログレベル
CONFIG_DIR	.	YAML 設定ファイルのディレクトリ
SESSION_TIMEOUT_SECONDS	1800	セッションの非アクティブタイムアウト
MAX_CONCURRENT_SESSIONS	100	同時セッションの最大数
RATE_LIMIT_GLOBAL	60	1分あたりのリクエスト数（全体）
RATE_LIMIT_WRITE	20	1分あたりの書き込み操作数

セキュリティ

2層のセキュリティモデル

1. MCP ゲートウェイの制限（YAML 設定とハードコードされた安全策）— Odoo への呼び出しが行われる前に、機密モデル、危険なメソッド、特権フィールドをブロックします
2. Odoo の組み込み ACL — ir.model.access と ir.rule を使用して、実際のレコードに対するユーザーごとのアクセスを強制します

モデルの制限レベル

レベル	効果	例
always_blocked	管理者を含め、誰もアクセスできません	ir.config_parameter、res.users.apikeys
admin_only	管理者ユーザーのみアクセスできます	ir.model、ir.model.fields
admin_write_only	全員が読み取り可能で、書き込みには管理者権限が必要です	res.company、res.currency

ハードコードされた安全ガードレール

これらは YAML 設定で上書きできません。

ブロック対象のモデル（32）：ir.config_parameter、res.users、res.users.apikeys、res.users.log、ir.cron、ir.module.module、ir.model.access、ir.rule、ir.mail_server、ir.ui.view、ir.actions.server、ir.logging、ir.attachment、ir.exports、ir.exports.line、iap.account、auth.totp.wizard、auth.totp.device、payment.token、payment.provider、base.automation、digest.digest、res.config.settings、change.password.wizard、change.password.user、base.module.update、base.module.upgrade、base.module.uninstall、fetchmail.server、bus.bus、mail.mail、mail.template

読み取り専用モデル（8）：mail.message、mail.followers、mail.activity、discuss.channel、mail.notification、mail.compose.message、mail.alias、discuss.channel.member（全員に対して読み取りは許可され、書き込みはブロックされます）

書き込みがブロックされるフィールド（10）：password、password_crypt、groups_id、totp_secret、signup_token、signup_type、signup_expiration、api_key、share、active

ブロック対象のメソッド（29）：sudo、with_user、with_company、with_context、with_env、with_prefetch、_auto_init、_sql、_register_hook、_write、_create、_read、_setup_base、_setup_fields、_setup_complete、init、_table_query、_read_group_raw、name_create、load、import_data、export_data、flush_recordset、invalidate_recordset、_search_panel_select_range、_search_panel_select_multi_range、_search_panel_domain_image、_search、_read_progress_bar

その他のセキュリティ機能

• ブルートフォース攻撃対策 — ユーザー名ごとのロックアウト（5 回失敗 → 5 分）と、接続元 IP／接続ごとのロックアウト（30 回失敗 → 15 分）を適用し、ユーザー名を切り替える攻撃をブロックします。ロックアウトの期間は固定されており、追加の試行によって延長されません（DoS 耐性）。
• 認証情報ラッパー — パスワード／セッション ID は、漏えいを防ぐ __repr__／__str__、使用時に明示的に呼び出す .reveal()、終了時に呼び出す .clear() を備えた Credential クラスに保存されます。
• サーバー側での管理者確認 — 認証後に has_group('base.group_system') を使って is_admin を再確認し、改ざんされた認証レスポンスから保護します。
• プライベートメソッドガード — アンダースコアで始まるメソッド（_compute_*、_inverse_* など）は、明示的に許可リストに登録されていない限り、管理者を含む全員に対してブロックされます。
• レート制限 — セッションごとのトークンバケットを使用し、全体用と書き込み用の予算を分けます。
• RBAC — ユーザーグループによるツールレベルのアクセス制御、フィールドレベルのレスポンスフィルタリング、return_dropped=True による透過的な除外レポート。
• 入力検証 — モデル名、メソッド名、フィールド名、ドメインフィルター、ORDER BY 句、時間演算子を含むグループ化、書き込み値（サイズ／深さ／型）。
• IDOR 対策 — プラグインツールのデータアクセス範囲を認証済みユーザーに限定します。
• 監査ログ — 許可および拒否されたすべての操作について、構造化 JSON ログを記録します。
• エラーのサニタイズ — エラーメッセージから内部 URL、SQL 断片、ファイルパス、スタックトレースを除去します。
• XXE 対策 — XML-RPC のレスポンスを defusedxml で解析します。
• ドメイン検証 — Odoo のドメインフィルターについて、演算子、フィールド名、値の型、ネストの深さ、リストのサイズを検証します。
• セッション期限切れ時の再試行 — JSON-RPC は OdooSessionExpiredError の場合にのみ再試行し、一般的な認証エラーでは再試行しません（アクセス拒否時に往復処理が二重になりません）。

認証

Odoo 標準の認証方式を 3 つ利用でき、カスタムアドオンは不要です。

方式	プロトコル	用途
api_key	XML-RPC	サーバー間通信、CI/CD パイプライン
password	JSON-RPC	インタラクティブユーザー、Claude Desktop
session	JSON-RPC	既存のブラウザーセッションの再利用（開発用）

# Example: login via the MCP tool
> login(method="password", username="admin", credential="admin", database="mydb")

コア MCP ツール（13）

ツール	説明
login	Odoo で認証します（api_key / password / session）
list_models	アクセス可能なモデルをメタデータとキーワードフィルター付きで一覧表示します
get_model_fields	オプションのフィルターを指定して、モデルのフィールド定義を取得します
search_read	ドメインフィルター、フィールド選択、並べ替えを指定してレコードを検索します
get_record	ID を指定して単一のレコードを取得します
search_count	条件に一致するレコード数を取得します
create_record	新しいレコードを作成します（検証のみの dry_run に対応）
update_record	既存のレコードを更新します（検証のみの dry_run に対応）
delete_record	ID を指定して単一のレコードを削除します（dry_run に対応）
read_group	時間演算子（date:month、date:quarter など）を使って、グループ化したデータを集計して読み取ります
get_defaults	create_record の前に Odoo のデフォルト値をプレビューします
get_onchange	フィールドによる副作用をプレビューします（RBAC フィルタリング対応）
execute_method	許可されたモデルメソッドを呼び出します（dry_run に対応）

ワークフローツール（2）

ツール	説明
get_create_requirements	レコード作成前に必須フィールドと検証ルールを取得します
get_record_actions	既存のレコードで利用可能なワークフローアクションを取得します

MCP リソース（6）

URI	説明
odoo://models	アクセス可能なすべてのモデルを一覧表示します
odoo://models/{name}	フィールド定義を含むモデルの詳細
odoo://record/{model}/{id}	RBAC によるフィールドフィルタリングを適用した単一レコードのデータ
odoo://schema/{model}	型情報と重要度ランクを含むフィールドスキーマ
odoo://categories	件数を含むモデルカテゴリ
odoo://workflow/{model}	モデルのステージとアクションを含むワークフロー定義

MCP プロンプト（12）

プロンプト	説明
analyze_model	モデル構造の包括的な分析
explore_data	自然言語によるデータ探索ガイド
create_workflow	モデル固有のワークフローを順を追って案内します
compare_records	レコードの並列比較
generate_report	分析レポートの生成
discover_custom_modules	カスタムモジュールの検出と理解
debug_access	アクセスと権限の問題のトラブルシューティング
workflow_guide	モデルのワークフローを実行するためのステップごとのガイド
record_creation_guide	フィールド検証を伴うレコード作成ガイド
bulk_operations	一括操作を安全に実行するためのガイド
field_mapping	Odoo バージョン（v17/v18/v19）間のフィールドのマッピング
data_migration	モデル間またはバージョン間でデータを移行するためのガイド

組み込みドメインプラグイン

HR プラグイン

ツール	説明
check_in	出勤を記録します
check_out	退勤を記録します
get_my_attendance	出勤記録を表示します（月フィルター対応）
get_my_leaves	休暇申請を表示します（状態フィルター対応）
request_leave	休暇を申請します
get_my_profile	従業員プロフィールを表示します

Sales プラグイン

ツール	説明
get_my_quotations	見積もり／注文を一覧表示します（状態フィルター対応）
get_order_details	明細項目を含む注文の全詳細
confirm_order	下書きまたは送信済みの見積もりを確定します
get_sales_summary	集計済みの販売統計を表示します（期間フィルター対応）

Project プラグイン

ツール	説明
get_my_tasks	割り当てられたタスクを一覧表示します（状態／プロジェクトフィルター対応）
get_project_summary	プロジェクト統計：ステージ別のタスク数、期限超過
update_task_stage	タスクを別のステージに移動します

Helpdesk プラグイン

ツール	説明
get_my_tickets	割り当てられたチケットを一覧表示します（状態／優先度フィルター対応）
create_ticket	新しいヘルプデスクチケットを作成します
update_ticket_stage	チケットを別のステージに移動します

カスタムモジュールのサポート

Python コードを書かずに、カスタム Odoo モジュールを追加できます。model_access.yaml を編集してください。

custom_models:
  full_crud:
    - custom.delivery.route
    - custom.warehouse.zone
  read_only:
    - custom.delivery.log

allowed_methods:
  custom.delivery.route:
    - action_dispatch
    - action_complete
    - action_cancel

すると、すべての CRUD ツール（search_read、create_record、update_record、delete_record）と execute_method が、完全なセキュリティ適用のもとでカスタムモデル上でも動作します。

プラグインシステム

pip でインストール可能なプラグインを使って、ゲートウェイを拡張できます。

from odoo_mcp_gateway.plugins.base import OdooPlugin

class ManufacturingPlugin(OdooPlugin):
    @property
    def name(self) -> str:
        return "manufacturing"

    @property
    def required_odoo_modules(self) -> list[str]:
        return ["mrp"]

    @property
    def required_models(self) -> list[str]:
        return ["mrp.production", "mrp.bom"]

    def register(self, server, context):
        @server.tool()
        async def get_production_orders(...):
            ...

pyproject.toml のエントリーポイントを使って登録します。

[project.entry-points."odoo_mcp_gateway.plugins"]
manufacturing = "my_package:ManufacturingPlugin"

設定ファイル

ファイル	用途
config/restrictions.yaml	モデル／メソッド／フィールドのブロックリスト（3 層）
config/model_access.yaml	モデルごとのアクセス方針、許可されたメソッド、機密フィールド
config/rbac.yaml	グループごとのロールベースのツールアクセスとフィールドフィルタリング
config/gateway.yaml	サーバー、接続、認証の設定

すべてのファイルには、詳細なインラインドキュメントを含む .example テンプレートがあります。コピーしてカスタマイズしてください。

cp config/restrictions.yaml.example config/restrictions.yaml
cp config/model_access.yaml.example config/model_access.yaml
cp config/rbac.yaml.example config/rbac.yaml

例：モデルの制限

# restrictions.yaml
restrictions:
  always_blocked:
    - my.secret.model
  admin_only:
    - hr.salary.rule
  admin_write_only:
    - res.company
  blocked_write_fields:
    - password_crypt
    - api_key
    - totp_secret

例：グループごとの RBAC

# rbac.yaml
rbac:
  tool_group_requirements:
    delete_record:
      - base.group_system
    execute_method:
      - base.group_erp_manager
  sensitive_fields:
    hr.employee:
      salary:
        required_group: hr.group_hr_manager

Docker

cp .env.example .env   # Edit with your Odoo settings
docker compose up

サービス：

• MCP ゲートウェイ — ポート 8080（streamable-http モード）
• Odoo 18 — 内部のみ（デフォルトではホストポートを公開しません）
• PostgreSQL — 内部のみ

ゲートウェイは、最小構成の Python イメージ内で非 root ユーザーとして実行されます。

CLI ツール

# Test Odoo connectivity
odoo-mcp-tools test-connection --url http://localhost:8069

# Validate all YAML config files
odoo-mcp-tools validate-config --config-dir config

# List configured model access policies
odoo-mcp-tools list-models --config-dir config

開発

git clone https://github.com/parth-unjiya/odoo-mcp-gateway.git
cd odoo-mcp-gateway
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=odoo_mcp_gateway --cov-report=term-missing

# Lint
ruff check src/ tests/

# Type check (strict mode)
mypy src/

ソース構成

src/odoo_mcp_gateway/
├── __main__.py                  # Entry point (stdio + HTTP)
├── server.py                    # FastMCP server setup, tool registration
├── config.py                    # Pydantic settings (env + .env)
├── client/
│   ├── base.py                  # OdooClientBase ABC, AuthResult
│   ├── jsonrpc.py               # JSON-RPC client (session auth)
│   ├── xmlrpc.py                # XML-RPC client (API key auth, defusedxml)
│   └── exceptions.py            # OdooError hierarchy (7 types)
├── core/
│   ├── auth/manager.py          # 3 auth strategies
│   ├── connection/manager.py    # Circuit breaker + retry
│   ├── version/                 # Odoo 17/18/19 detection + adapters
│   ├── workflow/
│   │   ├── definitions.py      # WorkflowDef, StateDef, TransitionDef dataclasses
│   │   ├── registry.py         # Workflow registration and lookup
│   │   └── stock_workflows/    # Built-in workflows (sale, purchase, HR, etc.)
│   ├── security/
│   │   ├── restrictions.py      # 3-tier model/method restrictions + hardcoded guardrails
│   │   ├── rbac.py              # Tool access + field filtering
│   │   ├── middleware.py        # Security pipeline + security_gate()
│   │   ├── rate_limit.py        # Token bucket rate limiter
│   │   ├── audit.py             # Structured audit logging
│   │   ├── sanitizer.py         # Error message sanitization
│   │   └── config_loader.py     # YAML config → Pydantic models
│   └── discovery/
│       ├── model_registry.py    # ir.model auto-discovery
│       ├── field_inspector.py   # fields_get with TTL cache
│       └── suggestions.py       # Category search + related models
├── tools/
│   ├── auth.py                  # login tool
│   ├── schema.py                # list_models, get_model_fields
│   ├── crud.py                  # search_read, create/update/delete, execute_method
│   └── workflow.py              # get_create_requirements, get_record_actions
├── resources/handlers.py        # 6 MCP resources (odoo:// URIs)
├── prompts/handlers.py          # 12 MCP prompt templates
├── plugins/
│   ├── base.py, registry.py     # Plugin ABC + entry_point discovery
│   └── core/                    # Built-in plugins (HR, Sales, Project, Helpdesk)
├── cli/tools.py                 # CLI: test-connection, validate-config
└── utils/                       # Domain builder, formatting, token budget

テスト

テスト 1,476 件が成功、コードカバレッジ 93％、mypy の strict チェックと ruff のチェックもクリーンです。

tests/unit/
├── client/          # JSON-RPC, XML-RPC, auth manager, XXE protection
├── security/        # Restrictions, RBAC, audit, rate limit, sanitizer, security_gate
├── discovery/       # Model registry, field inspector, suggestions
├── tools/           # All 13 MCP tools + input validation + dry_run
├── plugins/         # Plugin system + 4 domain plugins + IDOR protection
└── cli/             # CLI utility tools

# Run all tests
pytest tests/ -v

# Run specific area
pytest tests/unit/security/ -v
pytest tests/unit/tools/ -v
pytest tests/unit/plugins/ -v

# Coverage report
pytest tests/ --cov=odoo_mcp_gateway --cov-report=html

エラー処理

すべての Odoo エラーは 7 種類に分類されます。

エラー	原因
OdooConnectionError	Odoo サーバーに接続できません
OdooAuthError	認証情報が無効です
OdooAccessError	ir.model.access によってアクセスが拒否されました
OdooValidationError	フィールドの検証に失敗しました
OdooUserError	ビジネスロジックエラーです
OdooMissingError	レコードが見つかりません
OdooVersionError	サポートされていない Odoo バージョンです

MCP クライアントに届く前に、すべてのエラーメッセージがサニタイズされます。内部 URL、SQL の断片、ファイルパス、スタックトレースは自動的に取り除かれます。

既知の制限事項

• XML-RPC の認証情報の処理：API キー認証（XML-RPC）を使用する場合、プロトコル上必要なため、認証情報はすべての RPC 呼び出しで送信されます。本番環境では HTTPS を使用してください。（注：パスワードは repr() やトレースバックへの漏えいを防ぐ Credential ラッパーに保存されます。）
• HTTP モードのセッション分離：streamable-http トランスポートには、現在、セッション分離に関する既知の制限があります。ログインツール内で _current_session_key ContextVar が設定されますが、異なるリクエストコンテキストからの後続のツール呼び出しでは、最初に利用可能なセッションにフォールバックする場合があります。v0.3.0 でリクエストごとのミドルウェアが導入されるまでは、HTTP モードはシングルテナント専用（サーバープロセスごとにユーザー 1 人）としてデプロイしてください。stdio モードは設計上シングルセッションであり、この影響を受けません。

貢献

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/my-feature）
3. テストを追加して変更を行います
4. すべてのチェックが通ることを確認します：pytest && ruff check src/ tests/ && mypy src/
5. プルリクエストを送信します

ライセンス

MIT