Odoo Assistant MCP Server

Model Context Protocol（MCP）を介したOdoo仮想従業員です。このサーバーはOdooのビジネスロジック、レコード、ワークフローをLLMに公開し、Odooデータの安全なクエリ、作成、更新、操作を可能にします。

クイックスタート

1. インストール

サーバーを直接実行します：

uvx odoo-assistant

または、環境にインストールします：

uv pip install odoo-assistant

開発用にソースからインストールすることも可能です：

uv pip install git+https://github.com/singleflo/odoo-assistant-mcp

2. 環境変数の設定

2つの変数が必要です。その他は自動検出されるか、デフォルト値があります。

• ODOO_BASE_URL：OdooインスタンスのベースURL（例：https://mycompany.odoo.com）。

• ODOO_API_KEY：Odoo APIキー（Odoo 14+、設定 > ユーザー > APIキー > 新規作成で生成）。アカウントパスワードは受け付けられません。キーはユーザーごと、スコープ付きで、単独で取り消し可能です。

オプション設定：

• ODOO_DB：データベース名。インスタンスが1つのデータベースのみを提供する場合は自動検出されます。複数のデータベースを提供する場合は必須で、エラー時にすべてのデータベース名が表示されます。

• ODOO_USER：ログイン名。キーから検出されますが、最大59回の追加ラウンドトリップが発生する可能性があります。キー所有者のuidが60以上の場合、検出は失敗します。設定することでプローブを回避できます。

• ODOO_MCP_MAX_LEVEL：このサーバーが実行できる最高安全レベル。0から4（デフォルト：3）。これによりサーバーを読み取り専用にしたり、削除を許可したりできます。天井の選択を参照してください。

• ODOO_MCP_PROTECTED_HOSTS：このサーバーが書き込みを拒否するホストのカンマ区切りリスト（デフォルトは空で、パッケージに組み込まれたホストはありません）。リストされたホストへの読み取りは許可されます。書き込みには、意図的なオーバーライドとしてODOO_ALLOW_PROD_WRITE=yesが必要です。

Related MCP server: mcp-server-odoo

安全レイヤー

すべての書き込みとアクションは、Odooに到達する前に動的安全分類子を通過します。操作はレベルL0からL5に分類されます：

天井の選択

ODOO_MCP_MAX_LEVELは、このサーバーが実行できる最高レベルを設定します。各値は累積的で、自身のレベルとそれ以下のすべてを許可します：

数値を選ぶ前に知っておくべき2つの動作があります：

• 5はL5をアンロックしません。 両方のL5バリアントは、天井が読み取られる前に拒否されます。L5_PRIVATEは、Odoo自体が_で始まるすべてのメソッドを拒否するため、どの天井でも提供できません。L5_UNKNOWNは、誰も分類していないメソッドは定義上、未レビューの影響を持つため拒否されます。そのようなメソッドを許可する方法は、safety_layer.pyのWRITE_L1/L3/L4に追加することです。コード内でレビューされ、設定によってではありません。

• 無効な値は起動を拒否します。 ODOO_MCP_MAX_LEVEL="O"はデフォルトにフォールバックするのではなくエラーを発生させます。なぜなら、デフォルトは書き込み可能だからです。タイプミスによって、読み取り専用だと思っていたサーバーが書き込み可能になることを防ぎます。

天井は人間によって帯域外で設定され、起動時にプロセス環境から読み取られます。このサーバーに対して実行されるモデルは天井を上げることはできません。呼び出しが天井を超えた場合、拒否メッセージには必要なレベルが示されるため、エージェントは操作が何を変更するかを説明し、決定をあなたに委ねることができます。

これはこのサーバーの権限であり、アカウントの権限ではないことに注意してください。シェルアクセスを持つエージェントは、Odooを直接呼び出すことでMCPサーバーを常にバイパスできます。クライアントに関係なく保持しなければならない制限は、APIキーが属するユーザーのOdooアクセス権限に設定する必要があります。そこではOdooサーバーがそれを強制します。

Odooバージョンサポート

Odoo 14.0はサポートされる絶対最小バージョンです。このサーバーはAPIキーのみを使用して認証するため、Odoo 13以前には存在しません。

APIキー生成パス

APIキーを生成するには、Odooインスタンスにログインし、次の場所に移動します： 設定 / マイプロフィール → アカウントセキュリティ → 新しいAPIキー

トランスポートと非推奨に関する注意

クライアントは、ネイティブJSON-2 APIが/json/2/<model>/<method>で利用可能かどうかを自動的に検出し（Authorization: bearer <API_KEY>を使用）、利用できない場合はXML-RPCにフォールバックします。XML-RPCとJSON-RPCはOdoo 19で非推奨となり、Odoo 22で削除される予定です。

ソース

• Odoo 14.0 外部APIドキュメント（APIキーの紹介）

• Odoo 19.0 外部APIドキュメント（JSON-2）

• Odoo 19.0 外部RPC APIドキュメント（XML-RPC非推奨）

• Odoo 標準・拡張サポートポリシー（サポートタイムライン）

ツールとリソース

サーバーは19のツールと2つのリソースタイプを公開します：

ツール

1. search_read：1回の呼び出しでレコードを検索して読み取ります（Odoo search_read）。

2. read_record：IDで1つのレコードを読み取り、常に名前付きフィールドを使用します。

3. count_records：ドメインに一致するレコードをカウントします（Odoo search_count）。

4. instance_overview：接続されたインスタンスの概要（バージョン、会社、エリアごとのボリューム、社内モジュール、異常）を要約します。

5. required_fields：モデルに対するcreateの前にOdooが要求するもの、適用されるデフォルト値、および既存のレコードが実際にどのように使用しているかをリストします。

6. create_record：レコードを作成し、unique_onが指定されている場合は既存の一致を再利用します。

7. write_record：1つのレコードにフィールド値を書き込み、実際に変更された内容を報告します。

8. run_action：ワークフローメソッドを実行し、その後に残された状態を報告します。

9. cancel_record：action_cancelを使用してレコードをキャンセルし、返されたウィザードに従います。

10. notify_user：レコードのチャッターでユーザーに通知します。デフォルトは内部通知です。

11. create_activity：アクティビティをスケジュールします。期限を伴う唯一の通知です。

12. download_docs：レコードのすべてのドキュメントをディスクに保存します（チャッターファイルを含む）。

13. generate_pdf：レコードのPDFをレンダリングし、保存場所を返します。

14. list_message_targets：メッセージを送信できる相手とその場所（プレゼンス（オンライン/離席/オフライン）を持つ内部ユーザー、および呼び出し元の開いている会話）をリストします。送信前にこれを問い合わせてください。

15. read_conversation：Discussの会話を新しい順に読み取ります。

16. send_direct_message：1対1のDiscussメッセージを送信し、ユーザーのチャットシステムトレイにリアルタイムで表示されます。メールは送信されず、通知設定に関係なくユーザーに届きます。

17. send_channel_message：既存のDiscussチャンネルに投稿します。非従業員がいるルームは拒否します。

18. explore_module：ライブインスタンスに問い合わせてモジュールの構造を発見します。

19. list_known_modules：このサーバーが学習したモジュール（名前、生成日、レコード）をリストします。

ツール10-11（notify_user、create_activity）はレコードに関する通知を行い、受信箱のベルに届きます。ツール14-17はDiscussの会話で、チャットシステムトレイに届きます。「ユーザーXにメッセージ」は2番目の種類で、notify_userではなくsend_direct_messageです。

リソース

• odoo://skill：Odooアシスタントスキルの指示にアクセスします。

• odoo://ref/*：探索されたモジュールの生成されたリファレンスドキュメントにアクセスします。

ホスト設定例

以下の各例には、重要なものだけが含まれています。2つの必須変数と天井です。天井は、このサーバーが書き込み可能かどうかを決定する唯一の設定で、人間が所有するファイルに表示されます。データベースとログインは自動検出され、3が天井のデフォルトです。引用符に注意してください。環境値は文字列です。

Claude Desktop

claude_desktop_config.jsonにこれを追加します：

{
  "mcpServers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_MCP_MAX_LEVEL": "3"
      }
    }
  }
}

Cursor

.cursor/mcp.jsonに追加するか、Cursor設定UIで設定します：

{
  "mcpServers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_MCP_MAX_LEVEL": "3"
      }
    }
  }
}

VS Code Copilot

VS Codeのsettings.jsonに追加します：

{
  "mcp.servers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_MCP_MAX_LEVEL": "3"
      }
    }
  }
}

opencode

プロジェクトのopencode.jsonまたは.opencode/opencode.jsonに追加するか、~/.config/opencode/opencode.jsonに追加してサーバーをどこでも利用できるようにします：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "odoo-assistant": {
      "type": "local",
      "enabled": true,
      "command": [
        "uvx",
        "odoo-assistant"
      ],
      "timeout": 120000,
      "environment": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_MCP_MAX_LEVEL": "3"
      }
    }
  }
}

opencodeの構造は上記のホストとは異なり、そのままでは拒否されます。キーはmcp（mcpServersではない）、typeは必須、commandはプログラムとその引数を保持する単一の配列（別個のargsはありません）、環境ブロックはenvironment（envではない）です。

timeoutは意図的に設定してください。デフォルトは5000 msで、セッションの最初の呼び出しは認証に加え、instance_overviewの場合は数十回のXML-RPCラウンドトリップが発生します。実インスタンスに対しては5秒を優に超えます。

opencodeは設定を起動時に一度だけ読み取り、ホットリロードしないため、編集後は終了して再起動してください。ここで変更した内容（天井を含む）は、次回起動時にのみ有効になります。

ChatGPT（カスタムコネクタ）

このサーバーをカスタムコネクタ経由でChatGPTに接続するには：

1. 設定 → コネクタ → コネクタを追加 に移動します。

2. サーバーURLを入力するか、レジストリから選択します。

3. プロンプトが表示されたら、Odooの認証情報を入力します。

Hermes

Hermes CLIを使用してサーバーを追加します：

hermes mcp add odoo-assistant \
  --env ODOO_BASE_URL=https://mycompany.odoo.com \
  --env ODOO_API_KEY=your-api-key-here \
  --env ODOO_MCP_MAX_LEVEL=3 \
  --args run odoo-assistant

例ではオプションの変数は省略されています。インスタンスが複数のデータベースを提供する場合は ODOO_DB を、uidプローブをスキップする場合は ODOO_USER を、デフォルトの 3 から上限を変更する場合は ODOO_MCP_MAX_LEVEL を設定してください。

ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については LICENSE ファイルを参照してください。