odoo-surface-mcp

OdooSurface MCP

AI エージェントが Odoo にユーザーと同等のアクセスで接続できます。認証済みユーザーがブラウザーで実行できる操作のみが可能です。

前提条件

• Node.js 18 以降（npx が付属しているため、追加のインストールは不要です）
• 稼働中の Odoo インスタンス（15.0 以降、CE または EE）。各呼び出しのバージョンごとの動作については、docs/compatibility.md を参照してください。
• MCP 対応クライアント（VS Code、Claude Desktop、Claude Code、Cursor など）

MCP クライアントの設定

MCP クライアントの設定ファイル（例：Claude Desktop の claude_desktop_config.json）に以下を追加します。

{
  "mcpServers": {
    "odoo-surface": {
      "command": "npx",
      "args": ["-y", "@suco/odoo-surface-mcp@latest"],
      "env": {
        "ODOO_URL": "http://localhost:8069",
        "ODOO_DB": "your_database",
        "ODOO_USER": "admin",
        "ODOO_PASSWORD": "admin"
      }
    }
  }
}

保存後、MCP クライアントを再起動してください。npx がパッケージを自動的にダウンロードして実行するため、追加のインストール手順は不要です。

認証

オプション A — .env ファイル（認証情報を MCP の設定ファイルに記載しない）

認証情報を MCP クライアントの JSON に記載する代わりに、MCP を実行するディレクトリに .env ファイルを作成します。

ODOO_URL=http://localhost:8069
ODOO_DB=your_database
ODOO_USER=admin
ODOO_PASSWORD=your_password

MCP クライアントの設定から env ブロックを削除してください。.env ファイルは自動的に読み込まれます。

オプション B — API キー（推奨、パスワードを保存しません）

Odoo 14 以降では、ユーザーはパスワードの代わりとなる個人用 API キーを生成できます。 各ユーザーが自分のアカウントからキーを生成します。管理者側のメニューはありません。

1. MCP が認証に使用するユーザーとしてログインします
2. ユーザーアバター（右上）をクリックし、Preferences を選択します
3. Account Security タブを開きます
4. API Keys の下にある New API Key をクリックします
5. 求められたらパスワードを入力し、キーに名前を付けて、生成されたキーをコピーします
6. ODOO_PASSWORD として使用します。実際のアカウントパスワードは保存されません

ODOO_URL=http://localhost:8069
ODOO_DB=your_database
ODOO_USER=admin
ODOO_PASSWORD=your_api_key_here

アカウントパスワードを変更せずに、同じ画面から API キーを個別に取り消すことができます。

高度な設定

複数の Odoo インスタンス

技術者は、複数の Odoo インスタンス（ローカル開発環境、ステージング、本番環境など）を使うことがよくあります。 各インスタンスには MCP 設定で固有の名前付きエントリーを割り当てます。それぞれが独立したプロセスとして実行され、 認証情報は完全に分離されます。AI クライアントからは、それぞれが個別のツール名前空間として認識されます。

{
  "mcpServers": {
    "odoo-local": {
      "command": "npx",
      "args": ["-y", "@suco/odoo-surface-mcp@latest"],
      "env": {
        "ODOO_URL": "http://localhost:8069",
        "ODOO_DB": "dev",
        "ODOO_USER": "admin",
        "ODOO_PASSWORD": "dev_api_key"
      }
    },
    "odoo-production": {
      "command": "npx",
      "args": ["-y", "@suco/odoo-surface-mcp@latest"],
      "env": {
        "ODOO_URL": "https://mycompany.odoo.com",
        "ODOO_DB": "prod",
        "ODOO_USER": "admin",
        "ODOO_PASSWORD": "prod_api_key"
      }
    }
  }
}

注: .env ファイルを使う方法（オプション A）は、複数インスタンスの設定では機能しません。どちらの プロセスも同じ作業ディレクトリを共有し、同じファイルを読み込むためです。代わりに、各エントリーに env ブロックを 設定してください。

デバッグモード

追加のツールを登録します：ping、echo、inspect_view、inspect_action、inspect_fields、dump_cache、clear_cache、restart_mcp。

"args": ["-y", "@suco/odoo-surface-mcp@latest", "--debug"]

ツール

レイヤー	ツール
ガイダンス	list_skills, get_skills, find_skill, list_workflows, get_workflows
検出	get_models, get_model_actions, get_model_interface
計画	get_available_actions
補助	list_records, get_record, search_records, read_group, get_fields, get_defaults, get_filters, list_pages, get_page_arch, list_snippets, get_snippet, list_attachments, download_binary, fetch_and_upload, translation_get, translation_update, translation_audit
インテント	create, update, execute_action, archive, post_message, schedule_activity, create_page, set_page_arch, set_page_visibility, upload_binary

アーキテクチャ

コア契約

エージェントが実行できるのは、認証済みユーザーがブラウザーで実行できる操作に限られます。範囲はユーザーのメニュー、ビュー、ACL によって制限され、それ以上の操作はできません。ツールの動詞は、生の ORM 操作ではなく、機能上の意図（公開、確認）を表します。検出は遅延的に行われ、エージェントは現在のプロンプトで必要なものだけを解決します。

階層化されたツールサーフェス

レイヤー	役割	呼び出すタイミング
0 — ガイダンス	エージェントが複数ステップの操作の前に参照する、標準的な手順（スキル、ワークフロー）です。副作用のない純粋なドキュメントです。	計画の前
1 — 検出	現在のユーザーが利用できるモデルと、到達可能な関連の範囲を特定します。	意図の解決時
2 — 計画ブリッジ	「この特定のレコードで、現時点で有効なものは何か」に答える、レコードの状態を考慮したアクションです。	レコードの特定後
3 — サポート	エージェントの計画に不足している情報を補うため、表立たずに使われる読み取り専用のデータ取得ツールです。	計画中を通じて
4 — 意図	ユーザーのリクエストを満たす変更操作です。ユーザーの UI 権限の範囲に制限されます。	最終実行

計画ループ

User prompt
  ├── Discovery       — what models/relations does this user have?
  ├── (optional)      — locate the specific record
  ├── Planning Bridge — what is live on that record right now?
  ├── Guidance        — consult skills/workflows for multi-step recipes
  └── Intent          — execute the mutation(s)

スキルとワークフローは skills/ と workflows/ に YAML フロントマター付きの Markdown として記述され、実行時にレイヤー 0 のツールとして公開されます。