odoo-assistant

Odoo 向け Singleflo

Model Context Protocol（MCP）経由で利用できる Odoo の仮想従業員です。odoo-assistant パッケージとして公開されています。このサーバーは Odoo のビジネスロジック、レコード、ワークフローを LLM に公開し、Odoo データの安全な照会、作成、更新、操作を可能にします。

Singleflo for Odoo は独立したプロジェクトであり、Odoo S.A. とは提携、推奨、後援の関係にありません。Odoo は Odoo S.A. の商標であり、このサーバーが連携するソフトウェアを示す目的でのみ記載しています。

クイックスタート

AI エージェントを使ってインストールします。 お使いのコンピューターに、Hermes、Claude Code、Claude Desktop、Codex、Cursor、opencode、または以下に記載されているホストのいずれかの AI アシスタントがすでにある場合は、このプロンプトを 1 つのメッセージとして貼り付けてください。

Please install "Singleflo for Odoo" (the MCP server `odoo-assistant`) so that you can work with my Odoo.
Open and follow, step by step, the instructions written for you at:
https://raw.githubusercontent.com/singleflo/odoo-assistant-mcp/main/docs/INSTALL-WITH-YOUR-AGENT.md
I am not technical. Talk to me in English, give me one simple step at a time and wait for my answer, and do all the technical work yourself.
When you need the Odoo API key, guide me through creating it screen by screen. Never ask me for my Odoo password.
At the end, check that you can read my Odoo and tell me what you set up.

同じプロンプトのイタリア語、スペイン語、チェコ語版は docs/INSTALL-PROMPT.md にあります。リンク先のページは、あなたではなくエージェント向けに書かれています。Odoo のアドレスを尋ね、API キーの作成を案内し、Odoo Online でデータベース名を確認し、uv をインストールし、ホストが読み込む設定ファイルを作成して、接続を検証するように指示します。何もインストールできない Claude.ai または ChatGPT では、ホスト型接続の利用方法を案内します。手動での手順は以下のとおりです。

1. インストール

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

uvx odoo-assistant

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

uv pip install odoo-assistant

開発用にソースからインストールすることもできます。

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

2. 環境変数を設定する

まだ API キーをお持ちでない場合

Odoo API キーの作成方法 → — 各手順のスクリーンショット付きで、7 つの手順を説明しています。

簡単に説明すると、アバター → Preferences → Account Security → New API Key の順に選択します。アカウントのパスワードとは異なり、キーは Odoo ユーザーごとに発行され、そのユーザーとまったく同じ権限を持ちます。また、キーの値が表示されるのは一度だけです。

• ODOO_BASE_URL：常に必須です。末尾にスラッシュを付けずに、Odoo インスタンスのベース URL を指定します（例：https://mycompany.odoo.com）。
• ODOO_API_KEY：常に必須です。Odoo API キーを指定します（Odoo 14 以降。上記の説明、またはdocs/api-key.mdを参照してください）。アカウントのパスワードは使用できません。キーはユーザーごとに発行され、アクセス範囲を限定でき、単独で無効化できます。Odoo 19 では、説明と有効期限（最長 3 か月）も必要です。
• ODOO_DB：Odoo Online（SaaS、*.odoo.com）では必須で、それ以外では任意です。Odoo Online では、データベース一覧のエンドポイントが無効になっています。そのため、データベース名を自動検出できず、データベースが原因であることを示す手がかりもないまま、すべてのツール呼び出しが「Error executing tool」という不明瞭なエラーで失敗します。ODOO_DB を設定すれば、同じ設定ですぐに接続できます。SaaS のデータベース名は、わかりやすいサブドメイン名とは異なり、mycompany16-prod-12345678 のようなサフィックスが付いています。/web/database/selector または Odoo.com のアカウントページで確認できます。それ以外では、インスタンスがデータベースを 1 つだけ提供している場合は自動検出され、複数提供している場合は必須です。
• ODOO_USER：必須ではありません。省略すると、クライアントは res.users の uid 1～59 を調べ、キーが応答するユーザーを使用します。初回の呼び出しで最大 59 回の追加の往復が発生し、キーの所有者の uid が 60 以上の場合は失敗します。設定すれば、この処理コストをなくせます。ログイン名（例：[email protected]）を指定してください。値が間違っていると、Odoo の authenticate() は例外を発生させずに False を返すため、権限エラーのように見えます。
• ODOO_MCP_ALLOW：任意です。デフォルトは * で、拒否リストに含まれていないすべてのメソッドを許可します。値に none を指定すると、サーバーは読み取り専用になります。ライブの会社データを読み取るためにエージェントを接続する場合は、この設定を使用してください。それ以外の値は、メソッド名をカンマで区切ったリストです。下記の「エージェントに許可する操作」を参照してください。
• ODOO_MCP_DENY：任意です。未設定の場合、デフォルトの拒否リスト（unlink、archive、action_cancel、button_cancel、action_reverse、action_draft、mailing.mailing:action_send）が適用されます。値を設定すると、このリスト全体が置き換えられます。下記の「エージェントに許可する操作」を参照してください。
• ODOO_MCP_ALLOW_UNLINK：任意です。デフォルトでは無効です。yes、true、1（大文字と小文字は区別しません）を指定すると、unlink が許可されます。どちらのリストに追加しても許可できません。下記の「エージェントに許可する操作」を参照してください。
• ODOO_MCP_DATA_DIR：任意です。このサーバーが書き込むすべてのデータ（インスタンスプロファイルを含む）の保存先です。デフォルトでは、プラットフォーム固有のデータディレクトリを使用します。Windows では %LOCALAPPDATA%\odoo-assistant、macOS では ~/Library/Application Support/odoo-assistant、それ以外では $XDG_DATA_HOME/odoo-assistant（未設定の場合は ~/.local/share/odoo-assistant）です。

エージェントに許可される操作

すべての書き込みと操作は、Odoo に届く前にゲートを通過します。ゲートは、ホストの設定ファイルで管理する二つのリストと、呼び出し時にプロセス環境から読み取る値を使い、メソッド名に基づいて呼び出しを判定します。

• ODOO_MCP_ALLOW — 実行を許可するものです。未設定または空の場合は * となり、拒否リストで拒否されないすべてのメソッドが許可されます。値を none のみにすると、サーバーは読み取り専用になります。
• ODOO_MCP_DENY — 実行を拒否するものです。未設定または空の場合は、デフォルトのリストが使われます。 unlink、archive、action_cancel、button_cancel、action_reverse、 action_draft、mailing.mailing:action_send。値を設定すると、そのリストに追加されるのではなく、リスト全体が置き換えられます。そのため、有効な拒否対象はホストの設定ファイルで指定した名前だけになります。action_cancel を再び許可するには、ODOO_MCP_DENY=unlink とします。

各項目は、すべてのモデルでそのメソッドに一致する method、または特定のモデルでそのメソッドに一致する model:method のいずれかです。一致判定は文字列の完全一致です。プレフィックスや部分文字列では一致しないため、action_send が action_send_and_print に一致することも、action_cancel が button_cancel に一致することもありません。人間がこれらの名前を確認して承認しているため、より緩い一致では誰も確認していない類似の名前まで通してしまいます。拒否判定は許可判定より先に行われるため、両方のリストにある名前は拒否されます。

モデルを指定する方法は、実測したケースで必要となります。ある稼働中のインスタンスでは、31 のモデルが action_send に応答しますが、使うべきなのは Evolution ウィザードだけです。mailing.mailing のものは、1 回の呼び出しで顧客全体にメールを送信できます。そのため、デフォルトの拒否リストでは項目を mailing.mailing:action_send と指定し、他のすべての場所では action_send を引き続き使えるようにしています。

リストの対象外となるルールが四つあります。

• unlink は、二つのリストより先に判定されます。 ODOO_MCP_ALLOW や ODOO_MCP_DENY のどの値を使っても削除は許可されません。許可できるのは ODOO_MCP_ALLOW_UNLINK だけです。値は、大文字と小文字を問わず yes、true、1 のいずれかです。削除は取り消せない唯一の操作であり、カンマ区切りのリストに名前を記載するだけで許可できてはなりません。
• archive は仮想名です。 action_archive と、active: False を含む write のどちらも、この名前としてリストで判定されます。そのため、 archive を拒否すれば、どのような名前で指定されてもレコードの非表示化が拒否されます。
• プライベートメソッドは、リストの内容にかかわらず常に拒否されます。 Odoo 自体が _ で始まるメソッドをすべて拒否するため、リストから実行できるものはありません。
• 読み取りはどちらのリストも通りません。 読み取りはリストで制御すべき効果を持たないためです。これらの設定にかかわらず、account.move の構造ガードは引き続き適用されます。請求書、仕入先請求書、仕訳を混在させたクエリは、リストの内容にかかわらず拒否されます。意味のない読み取りそのものが危険となるためです。

設定	許可される内容
ODOO_MCP_ALLOW=none	読み取りのみです。このサーバーで行う操作によってレコードが変更されることはありません。本番環境のライブデータに接続するエージェント向けの設定です。
何も設定しない	デフォルトです。 デフォルトの拒否リストにある七つのメソッド以外はすべて許可されます。レコードの作成、書き込み、受注の確認、請求書の転記、活動の予約、ユーザーへのメッセージ送信ができます。
ODOO_MCP_ALLOW_UNLINK=yes	デフォルトの設定に unlink を加えたものです。拒否リストは変更されないため、独自に ODOO_MCP_DENY を設定するまでは、archive と action_cancel は引き続き拒否されます。

リストは人間が帯域外で設定するもので、このサーバーに接続するモデルが変更することはできません。ゲートが呼び出しを拒否すると、その理由として、呼び出しの内容、判定の根拠となった項目、判定結果を変える変数が示されます。そのため、エージェントは操作によって何が変更されるはずだったかを説明し、判断をユーザーに委ねることができます。

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

データベースとログイン：設定が必要な場合

どの環境でも必須なのは ODOO_BASE_URL と ODOO_API_KEY だけです。ODOO_DB と ODOO_USER は自動検出されますが、その検出が成功するかどうかは インスタンスのホスティング方法によって異なります。

データベースは次の2段階で、この順に検索されます。まず /xmlrpc/db に対する list()、次に /web/session/get_session_info への POST です。後者は認証情報を必要とせず、 list_db = False によって最初の方法でデータベース名が隠されていても、その名前を返します。ログイン名を尋ねることはありません。API キーは特定の1ユーザーにのみ属し、 execute_kw でそのユーザーの uid と組み合わせてのみ使用できるため、クライアントは res.users を検索し、uid 1 から59までを調べて所有者を特定します。

ホスティング	ODOO_DB	ODOO_USER	理由
Odoo Online（*.odoo.com、SaaS）	必須	任意	実測では、データベース一覧エンドポイントは無効になっています。名前がないと、すべてのツール呼び出しが、データベースが原因だと分かる手がかりのない不明瞭な「Error executing tool」で失敗します。SaaS の名前はサブドメインではなく、mycompany16-prod-12345678 のようなサフィックス付きで、/web/database/selector で確認できます。
Odoo.sh	任意	任意	1つのブランチで提供されるデータベースは1つで、セッション情報のフォールバック処理がその名前を返します。稼働中のブランチでのテストは未実施です。最初の呼び出しが失敗する場合は設定してください。
オンプレミス、データベースが1つ	任意	任意	どちらの段階でも、検出によって1つの名前が返されます。
オンプレミス、データベースが複数	任意。ただし設定すると便利	任意	必須ではありません。検出エラーに見つかったデータベース名が表示され、1つ選ぶよう促されるため、失敗の理由は明確です。設定すると、その往復処理を省略でき、曖昧さも解消されます。

どのホスティング環境でも、ODOO_USER 単独で必須になることはありません。設定すると、 セッション内の最初の呼び出しで最大59回の検出処理を省略でき、API キー所有者の uid が 60以上の場合は必須になります。これは検出処理が uid 1から59までしか検索しないためです。 設定する値はログイン名（例：[email protected]）です。誤った値を指定すると、誤解を招く形でエラーになります。Odoo の authenticate() は不明なログイン名に対して例外を発生させず False を返すため、入力ミスではなく権限エラーのように見えます。

Odoo のバージョン別

Odoo 14から18は、この点では同じ動作をします。 XML-RPC ではすべての execute_kw 呼び出しにデータベース名が含まれるため、クライアントは認証を開始する前に その名前を把握していなければなりません。これが、まさに検出処理が存在する理由です。

Odoo 19 では、X-Odoo-Database HTTP ヘッダーでデータベースを選択する JSON-2 API が追加されています。Odoo 公式ページのヘッダー表では、この項目は任意とされていますが、同ページのデータベースの節では、任意でなくなる条件が具体的に説明されています。それは、「1つの Odoo サーバーが複数のデータベースをホストし、dbfilter が Host ヘッダーを使用するように設定されていない場合は必須」です。また、同じページの別の箇所では、データベースは「同じドメインで複数のデータベースを利用できるシステムでのみ（X-Odoo-Database HTTP ヘッダーを介して）指定する必要がある」と説明されています。ホスト名によってすでにデータベースが決まる場合（Odoo Online、Odoo.sh、Host をキーにした dbfilter など）は、省略できます。

このサーバーのクライアントはまず JSON-2 を試します。Authorization: Bearer <key> を付けた /json/2/res.users/search_count への POST を1回行い、200 が返された場合は、そのセッションの通信方式として JSON-2 を使用します。それ以外の場合は XML-RPC にフォールバックします。送信するのは Authorization と Content-Type のみで、ほかのヘッダーは付けないため、X-Odoo-Database は設定されません。JSON-2 ではホスト側がデータベースを特定する必要があり、ODOO_DB が使われるのは XML-RPC の経路だけです。

Odoo のバージョンサポート

Odoo 14.0 がサポート対象となる最低バージョンです。このサーバーは API キーのみで認証するためです。API キーは Odoo 13 以前にはありません。

Odoo バージョン	API キー	XML-RPC	公式メンテナンス中（2026年8月）	サポートレベル／注記
≤ 13.0	なし	はい	いいえ	サポート対象外。API キーがないため、このサーバーは認証できません。
14.0	あり	はい	いいえ	プロトコル互換です。稼働中のインスタンスでは未テストです。
15.0	あり	はい	いいえ	プロトコル互換です。稼働中のインスタンスでは未テストです。
16.0	あり	はい	いいえ	稼働中の Enterprise インスタンスで検証済み：接続、認証、読み取り、instance_overview、Discuss ツール。世代間の違いは2点あり、サーバー側で処理されます。詳しくは以下の注記をご覧ください。書き込みシナリオは検証していません。
17.0	あり	はい	はい（2026年9月まで）	プロトコル互換です。稼働中のインスタンスでは未テストです。
18.0	あり	はい	はい（2027年9月まで）	主な対象バージョン。稼働中のインスタンスで検証済みで、完全にサポートされています。
19.0	あり	はい	はい（2028年9月まで）	プロトコル互換です。稼働中のインスタンスでは未テストです。API キーには説明と有効期限が必要です（最長3か月）。JSON-2 API では X-Odoo-Database ヘッダーでデータベースを選択します。上記の「データベースとログイン：設定が必要な場合」をご覧ください。

Odoo 16 から 17 への変更点は2つありますが、どちらも設定は不要です。

• Discuss の名称が変更されました。17 では mail.channel／mail.channel.member が discuss.channel／discuss.channel.member になりました。サーバーは インスタンスがどちらのペアを使用しているかを確認し、そのペアを使うため、 4つの Discuss ツールはどちらの世代でも動作します。
• サブスクリプションは sale.order に移動しました。17 より前は subscription_state フィールド自体がありませんでした。16 では、このセクションは instance_overview に表示されません。これは失敗ではなく、単に項目が存在しないことを意味します。

API キーの生成手順

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

図解付きの手順は docs/api-key.md をご覧ください。有効期間フィールド、Odoo 19 の有効期限ルール、キーの取り消し方法についても説明しています。

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

クライアントは、ネイティブの JSON-2 API が /json/2/<model>/<method> で利用可能かどうかを自動的に検出します（この API は 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 標準および延長サポートポリシー（サポート期間）

ツールとリソース

このサーバーは22個のツールと2種類のリソースを公開します。

ツール

1. search_read：1 回の呼び出しでレコードを検索して読み込みます（Odoo の search_read）。
2. read_record：ID で 1 件のレコードを読み込みます。常に名前付きフィールドを指定します。
3. read_long_field：長いテキストフィールドを分割して読み込みます。値が 5000 文字の結果上限を超える場合も、最後まで読み取れます。
4. count_records：ドメインに一致するレコード数を数えます（Odoo の search_count）。
5. group_records：レコードをグループ化し、バケットごとに件数（または集計値）を算出します（Odoo の read_group）。状態、ステージ、月ごとの合計などを確認できます。
6. instance_overview：接続中のインスタンスの概要をまとめます。バージョン、会社、領域ごとのデータ量、社内モジュール、異常などを確認できます。
7. required_fields：モデルでレコードを create する前に Odoo が要求する項目、適用されるデフォルト値、既存レコードでの実際の使用状況を一覧表示します。
8. describe_model：稼働中のインスタンスで定義されているモデルのフィールドを一覧表示します。名前、型、関連先、選択値、必須項目かどうかを確認できます。
9. create_record：レコードを作成します。unique_on が指定されている場合は、既存の一致するレコードを再利用します。
10. write_record：1 件のレコードにフィールド値を書き込み、実際に変更された内容を報告します。
11. run_action：ワークフローのメソッドを実行し、実行後の状態を報告します。
12. cancel_record：action_cancel を通じてレコードをキャンセルし、返されるウィザードに従って処理します。
13. notify_user：レコードのチャターでユーザーに通知します。デフォルトでは内部通知です。まずプレビューを表示し、ユーザーの承認後にのみ投稿します（下記参照）。
14. create_activity：アクティビティを予約します。期限を伴う唯一の通知です。
15. download_docs：チャターのファイルを含む、レコードのすべてのドキュメントをディスクに保存します。
16. generate_pdf：レコードの PDF を生成し、保存先を返します。
17. list_message_targets：メッセージを送信できる相手と場所を一覧表示します。プレゼンス（オンライン／離席中／オフライン）付きの内部ユーザーと、呼び出し元が参加中の会話も含まれます。送信前にこのツールを使用してください。
18. read_conversation：Discuss の会話を新しい順に読み込みます。
19. send_direct_message：1 対 1 の Discuss メッセージを送信します。メッセージはユーザーのチャットのシステムトレイにリアルタイムで表示されます。メールは送信されず、通知設定にかかわらず相手に届きます。まずプレビューを表示し、ユーザーの承認後にのみ送信します。
20. send_channel_message：既存の Discuss チャネルに投稿します。従業員以外が参加しているルームへの投稿は拒否されます。まずプレビューを表示し、ユーザーの承認後にのみ投稿します。
21. explore_module：稼働中のインスタンスを調べて、モジュールの構造を確認します。
22. list_known_modules：このサーバーが把握しているモジュールを、名前、生成日、レコード数とともに一覧表示します。

ツール 13〜14（notify_user、create_activity）はレコードについて通知し、受信トレイのベルに届きます。ツール 17〜20 は Discuss の会話で、チャットのシステムトレイに届きます。「ユーザー X にメッセージを送って」は後者に該当するため、notify_user ではなく send_direct_message を使用します。

ユーザーに代わってメッセージを送信する 3 つのツール（notify_user、 send_direct_message、send_channel_message）は、2 回呼び出す必要があります。1 回目は confirmation_token を指定せずに呼び出します。この時点では何も送信されず、リクエストが検証され、プレビュー（受信者、送信経路、メールを受け取るユーザー、メッセージ全文）とトークンが返されます。エージェントはプレビューを表示してユーザーに確認します。ユーザーの承認後にのみ、同じ引数とトークンを指定して再度呼び出します。このトークンは、プレビューされた引数と完全に一致する内容を一度だけ、10 分間承認します。承認後にメッセージが変更された場合は拒否され、送信されません。

リソース

• odoo://skill：Odoo アシスタントのスキル手順にアクセスします。
• odoo://ref/*：調査済みモジュールの生成されたリファレンスドキュメントにアクセスします。

ホストの設定例

以下の各例には、重要な項目だけが含まれています。必須の2つの変数と、Odoo Onlineでは検出できないデータベースです。ログイン情報は検出されます。「エージェントに許可する操作」にあるように、ODOO_MCP_ALLOW または ODOO_MCP_DENY を追加しない限り、ゲートはデフォルト設定のままです。値は文字列なので、引用符に注意してください。

何も動作しないときに設定漏れが最も多い変数が ODOO_DB であるため、どのスニペットにも含まれています。設定が必須の場合にのみ指定してください。詳しくは上記の「データベースとログイン情報：設定が必要な場合」を参照してください。JSONではコメントが使えないため、その注記はブロック内ではなくここに記載しています。TOMLとYAMLのスニペットには注記が含まれています。

以下の各スニペットは、そのホストの公式ドキュメントと照合済みです。出典は各スニペットの下の Source: 行に記載しています。ホストに1行の追加コマンドがある場合は、手動でファイルを編集せずに同じ設定を追加できるため、あわせて記載しています。

ホスト型サーバー：Claude.ai、ChatGPT、Codex

以下のセクションに記載された方法では、すべてご利用のマシン上でサーバーを実行します。同じ22個のツールを利用するもう1つの方法は、インターネット経由で https://odoomcp.singleflo.com/mcp に接続することです。Claude.ai、ChatGPT、Codexから直接アクセスできます。何もインストールする必要はなく、お使いの側で環境変数を設定する必要もありません。サーバーの同意ページでOdooのアドレスとAPIキーを使って一度サインインすれば、普段お使いのチャットからOdooにアクセスできます。他のすべてのセクションのローカル設定は、記載どおりにそのまま動作します。この2つの方法の違いは、サーバーの実行場所だけです。

ChatGPT Plugin Directoryの掲載版では、代わりに https://odoomcp.singleflo.com/openai/mcp に接続します。同じサーバー、サインイン、ポリシーを使いますが、OpenAIが許可していない run_action と explore_module を除くすべてのツールが利用できます。前者は任意のワークフローメソッドを実行し、後者は1つの引数で2つの操作から選択します。Claude.ai、Codex、ChatGPTの開発者モードでは、引き続き全22個のツールを利用できる /mcp を使用します。

同意ページでは、OdooのURL、APIキー、そして次のいずれかを選択します。readではエージェントがデータを参照でき、standardではレコードの作成、ワークフローの実行、アクティビティの予定設定も行えます。ホスト型サーバーでは削除を利用できません。どちらの選択肢でも、unlink にはアクセスできません。サインインし直してもう一方を選択すれば、後から選択を変更できます。

ローカル設定に ODOO_DB と ODOO_USER があるのと同じ理由で、追加の任意入力欄が2つあります。データベースはOdoo Onlineで必須であり、Odooログイン名はAPIキーを所有するユーザーのものです。ログイン名を空欄にすると、サーバーはuid 1から59を調べて所有者を特定します。この調査で特定できない場合は、ログイン名を入力してください。インスタンスの設定後に作成されたユーザーはuid 59を超えているため、その場合はログイン名を入力するまでサインインに失敗します。その際はページに案内が表示されます。

ホスト型サーバーが保存する情報：OdooのURLとAPIキー（保存時に暗号化）、サインイン時の本人情報（ハッシュのみを保存）、およびツールが生成するファイル（15分後に期限切れとなるリンクとしてのみ保存）。詳細は https://odoomcp.singleflo.com/privacy をご覧ください。同じドメインに https://odoomcp.singleflo.com/terms と https://odoomcp.singleflo.com/support もあります。

ホストごとの手順：Claude.aiとChatGPTはホスト型接続のみで、以下にそれぞれのセクションがあります。Claude CodeとCodexは上記のローカル設定を引き続き利用でき、ホスト型のワンライナーもそれぞれ追加されています。

ホスト型の部分もご自身で実行したい場合は、開発者ガイド docs/REMOTE.md で、ローカル実行、トンネル、デプロイまでの全手順を説明しています。

Claude Desktop

Claude Desktop は macOS と Windows のみで提供されており、サーバー設定は claude_desktop_config.json に保存されます。設定 → Developer → Edit Config から開くか、次の場所にあるファイルを直接編集してください。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\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_DB": "mycompany16-prod-12345678"
      }
    }
  }
}

Claude Desktop を完全に終了してから再度開いてください。起動時にファイルを読み込み、再読み込みは行いません。サーバーログは macOS では ~/Library/Logs/Claude/ に、Windows では %APPDATA%\Claude\logs に、サーバーごとに 1 つずつ保存されます。stdio サーバーは、出力する内容をすべて stderr に書き込みます。

出典：https://modelcontextprotocol.io/docs/develop/connect-local-servers

Claude Code

1 行追加するだけでサーバーを登録できます。-- は Claude Code 自身のオプションとサーバーを起動するコマンドを区切り、それ以降の内容はそのまま渡されます。

claude mcp add --env ODOO_BASE_URL=https://mycompany.odoo.com \
  --env ODOO_API_KEY=your-api-key-here \
  --env ODOO_DB=mycompany16-prod-12345678 \
  --transport stdio odoo-assistant -- uvx odoo-assistant

オプションの順序に注意してください。--env は KEY=value の組を受け取り、後続の入力も読み続けます。そのため、サーバー名を直後に置いてはいけません。間に少なくとも 1 つ別のオプション（ここでは --transport stdio）を入れてください。そうしないと、CLI は odoo-assistant を別の組として読み取り、拒否します。

--scope は設定の保存先を決めます。local（デフォルト：このプロジェクトのみ、自分だけ）、project（リポジトリのルートにある .mcp.json。コミットして共有）、または user（すべてのプロジェクト）です。手動で記述する場合は、同じ設定を .mcp.json または ~/.claude.json の mcpServers の下に追加します。

{
  "mcpServers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "mycompany16-prod-12345678"
      },
      "timeout": 120000
    }
  }
}

サーバーごとの timeout は、ツール呼び出しごとの実時間制限（ミリ秒単位）で、このサーバーに限り MCP_TOOL_TIMEOUT 環境変数より優先されます。MCP_TIMEOUT もミリ秒単位で、サーバーの起動時間を制限します。ここでは、セッション中の最初の instance_overview 呼び出しを除き、どちらも問題になりません。この呼び出しでは、認証に加えて数十回の XML-RPC 通信が行われます。編集後は /mcp パネルからサーバーに再接続するか、Claude Code を再起動してください。

上記の 1 行設定では、サーバーは自分のマシン上で動作します。Claude Code では、インストールも環境変数も不要なホスト型サーバーも利用できます。

claude mcp add --transport http odoo-assistant https://odoomcp.singleflo.com/mcp

最初のツール呼び出しでサインインが開始され、読み取りまたは標準のどちらかを選ぶ同意ページが表示されます。ホスト型の場合、利用可能な操作はここで決まり、ローカルの ODOO_MCP_* 変数では決まりません。また、削除は一切利用できません。

出典：https://code.claude.com/docs/en/mcp

OpenAI Codex CLI

Codex は MCP サーバーを TOML 形式で ~/.codex/config.toml に保存します。また、プロジェクトを信頼済みにすると、そのプロジェクトの .codex/config.toml に保存できます。テーブル名にはアンダースコアを使い、mcp.servers ではなく mcp_servers と記述します。ChatGPT デスクトップアプリ、Codex CLI、IDE 拡張機能はすべてこのファイルを読み込むため、一度設定すれば 3 つすべてで利用できます。

codex mcp add odoo-assistant \
  --env ODOO_BASE_URL=https://mycompany.odoo.com \
  --env ODOO_API_KEY=your-api-key-here \
  --env ODOO_DB=mycompany16-prod-12345678 \
  -- uvx odoo-assistant

同じ設定をファイルに記述すると、次のようになります。

[mcp_servers.odoo-assistant]
command = "uvx"
args = ["odoo-assistant"]
startup_timeout_sec = 30
tool_timeout_sec = 300

[mcp_servers.odoo-assistant.env]
ODOO_BASE_URL = "https://mycompany.odoo.com"
ODOO_API_KEY = "your-api-key-here"
# only when required, see "Database and login" above
ODOO_DB = "mycompany16-prod-12345678"

どちらのタイムアウトも 秒単位 です。startup_timeout_sec のデフォルトは 10 秒、tool_timeout_sec のデフォルトは 60 秒です。どちらも最初の instance_overview 呼び出しでのみ必要になるため、上記では両方を長めに設定しています。編集後、デスクトップアプリまたは IDE 拡張機能でサーバーの Restart を押してください。CLI の場合は新しいセッションを開始し、/mcp で確認します。

ホスト型サーバーは URL で追加し、サインインは専用のコマンドで行います。

codex mcp add odoo-assistant --url https://odoomcp.singleflo.com/mcp
codex mcp login odoo-assistant

codex mcp login を実行すると同じ OAuth フローが始まり、読み取りまたは標準のどちらかを選ぶ同意ページが表示されます。codex mcp logout odoo-assistant を実行すると接続が終了します。すべてのホスト型接続と同様に、読み取りは常に利用でき、書き込みの可否はサインイン時の選択に従います。削除は一切利用できません。

出典：https://developers.openai.com/codex/mcp

出典：https://developers.openai.com/codex/config-file/config-reference

ChatGPT

ChatGPT は、Web 上で Pro、Plus、Business、Enterprise、Education アカウント向けに提供されている開発者モードを通じて、ホスト型サーバーに接続します。

1. ChatGPT で 設定 → セキュリティとログイン を開き、開発者モードをオンにします。
2. chatgpt.com/plugins を開き、プラスボタンを押して、MCP URL https://odoomcp.singleflo.com/mcp の開発者モードアプリを作成します。
3. ChatGPT がサインインを開始し、サーバーの同意ページが表示されます。Odoo の URL と API キーを入力し、読み取りまたは標準を選択します。
4. 会話でプラスメニューから開発者モードを選び、Singleflo for Odoo アプリを選択します。

意図的にローカル用の設定例は記載していません。開発者モードでは HTTPS 経由でのみリモート MCP サーバーに接続するため、他のセクションの stdio 設定は適用されません。開発者モードの手順が不要になる ChatGPT の Plugin Directory への公開リスト掲載は予定されていますが、まだ実現していません。

エージェントに許可する操作は、サインイン時に一度だけ決定します。読み取り、または標準です。会話で何を求められても、削除はできません。

出典：https://developers.openai.com/plugins/deploy/connect-chatgpt

Claude.ai（Web、デスクトップ、モバイル）

Claude はカスタムコネクターとしてホスト型サーバーに接続します。カスタマイズ → コネクター → カスタムコネクターを追加を開き、サーバー URL として https://odoomcp.singleflo.com/mcp を貼り付けて確定します。Team および Enterprise プランでは、オーナーが組織の設定 → コネクターで一度追加します。その後、メンバーはカスタマイズ → コネクターから接続します。

初回使用時にサインインが開始され、同意ページが表示されます。Odoo の URL、API キー、および読み取りか標準かの選択肢が表示されます。

このリンクを開くと、名前と URL が入力済みの同じダイアログが表示されます。内容を確認して確定してください。確定するまでは何も追加されません。

https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Singleflo%20for%20Odoo&connectorUrl=https%3A%2F%2Fodoomcp.singleflo.com%2Fmcp

出典：https://claude.com/docs/connectors/custom/remote-mcp

出典：https://claude.com/docs/connectors/building/directory-vs-custom

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_DB": "mycompany16-prod-12345678"
      }
    }
  }
}

opencode の設定形式は上記のホストとは異なり、誤った形式は拒否されます。キーは mcp（mcpServers ではありません）で、type は必須です。command はプログラムと引数をまとめた単一の配列です（args は個別に指定しません）。環境設定ブロックは environment（env ではありません）です。

timeout は意図して設定してください。デフォルトは 5000 ms です。セッションの初回呼び出しでは、認証に加えて instance_overview のための多数の XML-RPC 往復通信が発生するため、実際のインスタンスでは簡単に 5 秒を超えます。120000 に設定してください。

opencode は起動時に設定を一度だけ読み込み、ホットリロードしません。編集後は終了して再起動してください。許可リストや拒否リストを含め、ここでの変更は次回の起動時にのみ反映されます。

出典：https://opencode.ai/docs/mcp-servers

Hermes

Hermes では、サーバーを ~/.hermes/config.yaml の mcp_servers: の下にある YAML で管理します。

mcp_servers:
  odoo-assistant:
    command: /Users/you/.local/bin/uvx
    args:
      - odoo-assistant
    env:
      ODOO_BASE_URL: https://mycompany.odoo.com
      ODOO_API_KEY: your-api-key-here
      # only when required, see "Database and login" above
      ODOO_DB: mycompany16-prod-12345678
    timeout: 120
    connect_timeout: 60
    enabled: true

この形式では、3つの点に注意が必要です。command は文字列で、プログラムのみを指定し、引数は別の args リストに指定します。これは、opencode の単一配列とは逆です。環境変数のブロックは env です。また、コマンドには絶対パスが必要です。Hermes はデスクトップアプリとして動作し、シェルの PATH を引き継がないため、単なる uvx では見つかりません。

ここでのタイムアウトはどちらもミリ秒ではなく秒単位です。timeout はツール呼び出しの上限で、デフォルトは 300 です。connect_timeout は初回接続の上限で、デフォルトは 60 です。上記の 120 は、最初の instance_overview 呼び出しに十分な余裕があります。編集後は再起動するのではなく、/reload-mcp でサーバーを再読み込みしてください。

hermes mcp add でこのエントリを作成することもできます。シグネチャは add <name> [--url URL] [--command CMD] [--auth oauth|header] [--args ...] です。ただし、--args は最後に指定してください。残りの argv をすべて受け取るため、その後に指定したものはすべて args に取り込まれ、認証情報がそこに入ってサーバーに渡らなくなります。

参照元：https://hermes-agent.nousresearch.com/docs/reference/mcp-config-reference

Cursor

プロジェクト内の .cursor/mcp.json に追加するか、サーバーをどこからでも利用できるようにするには ~/.cursor/mcp.json に追加します。または、サイドバーの Customize から設定できます。

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

Cursor は command、args、env、url、headers 内の ${env:NAME} を展開します。そのため、"ODOO_API_KEY": "${env:ODOO_API_KEY}" とすれば、コミットする可能性のあるファイルにキーを記載せずに済みます。呼び出しに失敗した場合は、Output パネルの MCP Logs に理由が表示されます。

参照元：https://cursor.com/docs/context/mcp

Windsurf

Windsurf の Cascade エージェントは、すべてのプラットフォームで1つのグローバルファイル ~/.codeium/windsurf/mcp_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_DB": "mycompany16-prod-12345678"
      }
    }
  }
}

Cascade パネルの MCPs アイコン、または Settings → Cascade → MCP Servers から開き、サーバーリストを更新してください。このファイルでは command、args、env 内の ${env:VAR_NAME} と ${file:/path/to/file} が展開されるため、API キーをこのファイルの外に置けます。Cascade ではエージェントが使用できるツールの合計が 100 個に制限されており、このサーバーはそのうち 22 個を使用します。

参照元：https://docs.windsurf.com/windsurf/cascade/mcp

VS Code と GitHub Copilot

VS Code のルートキーは mcpServers ではなく servers です。他のホストのドキュメントからエントリをコピーしても認識されません。プロジェクトと一緒にコミットする場合は、ワークスペース内の .vscode/mcp.json に追加してください。または、コマンドパレットから MCP: Open User Configuration を実行すると、ユーザープロファイルに保存され、すべてのワークスペースで使える設定を開けます。

{
  "servers": {
    "odoo-assistant": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "mycompany16-prod-12345678"
      }
    }
  }
}

コマンドラインからも同じエントリを書き込めます。

code --add-mcp "{\"name\":\"odoo-assistant\",\"command\":\"uvx\",\"args\":[\"odoo-assistant\"]}"

VS Code がサーバーを初めて起動するとき、信頼するかどうかを尋ねます。拒否すると、サーバーは起動しません。mcp.json のコードレンズ、またはコマンドパレットの MCP: List Servers を使って、サーバーの起動、停止、再起動や、出力の確認ができます。コミットするワークスペースファイルに API キーを直接記述するのは避けてください。VS Code には、まさにこの用途の入力変数が用意されています。

参照元：https://code.visualstudio.com/docs/copilot/customization/mcp-servers

Gemini CLI

Gemini CLI はすべてのセッションで settings.json の mcpServers（~/.gemini/settings.json）を読み込みます。また、プロジェクトのルートにある .gemini/settings.json はそのプロジェクトだけに適用され、こちらが優先されます。

gemini mcp add odoo-assistant uvx odoo-assistant \
  --env ODOO_BASE_URL=https://mycompany.odoo.com \
  --env ODOO_API_KEY=your-api-key-here \
  --env ODOO_DB=mycompany16-prod-12345678 \
  --scope user

同じ設定を展開すると、次のようになります。

{
  "mcpServers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "mycompany16-prod-12345678"
      },
      "timeout": 600000
    }
  }
}

timeout はリクエストのタイムアウト時間をミリ秒で指定するもので、デフォルトですでに 600000（10 分）に設定されています。そのため、最初の instance_overview 呼び出しでは何も設定する必要はありません。ここに行を示しているのは、より早くタイムアウトさせたい場合に変更するキーだからです。もう 2 つ、役立つ習慣があります。Gemini CLI はサーバーを起動する前に、継承した環境変数のうち *KEY*、*TOKEN*、*SECRET* に一致するものをすべてマスキングするため、環境変数を渡すにはこの env ブロックに名前を記述する必要があります。また、ブロック内の "$MY_VAR" はシェルから展開されます。編集後に CLI を再起動し、/mcp でサーバーを確認してください。

ソース：https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md

ソース：https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/cli-reference.md

Cline

Cline の CLI は ~/.cline/mcp.json を読み込みます。IDE 拡張機能では、Cline パネルの MCP Servers アイコンを開き、Configure タブに移動して Configure MCP Servers を押すと、拡張機能独自の設定 JSON が開きます。どちらも同じ mcpServers の形式を使用します。

{
  "mcpServers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "mycompany16-prod-12345678"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

autoApprove は空のままにしてください。これは確認なしで実行されるツールのリストです。このサーバーのゲート機能は、書き込み呼び出しが行われる前に内容を確認することの代わりにはなりません。cline mcp を実行すると、ファイルに触れずにサーバーの追加、編集、有効化、削除ができる対話型ウィザードが開きます。リクエストのタイムアウトは、このファイルのキーではなく、MCP 設定パネルにあるサーバーごとの設定です。最初の instance_overview 呼び出しがタイムアウトする場合は、そこで値を大きくし、同じパネルからサーバーを再起動してください。

ソース：https://docs.cline.bot/mcp/mcp-overview

Roo Code

Roo Code は 2 つのファイルを読み込みます。グローバル設定の mcp_settings.json は MCP 設定画面の下部にある Edit Global MCP ボタンから開き、プロジェクトごとの .roo/mcp.json はその隣の Edit Project MCP から開きます。存在しない場合、Roo が作成します。同じサーバー名が両方にある場合は、プロジェクト側の定義が適用されます。

{
  "mcpServers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "mycompany16-prod-12345678"
      },
      "alwaysAllow": [],
      "disabled": false,
      "timeout": 300
    }
  }
}

ここでの timeout はミリ秒ではなく秒で、1～3600 の値を指定でき、デフォルトは 60 です。すべての呼び出しには 60 秒で十分ですが、セッション中の最初の instance_overview 呼び出しだけはタイムアウトする可能性があるため、その場合は値を大きくしてください。同じ値は、サーバーのパネルにある Network Timeout ドロップダウンにも表示されます。Cline の説明にある理由から、alwaysAllow は空のままにしてください。編集後は、サーバーの横にある再起動ボタンを押してください。

.roo/mcp.json をコミットすると、サーバーをチームで共有できます。そのため、API キーはシステム環境変数に設定し、バージョン管理に入るファイルに直接書き込むのではなく、args 内で ${env:ODOO_API_KEY} として参照してください。

ソース：https://docs.roocode.com/features/mcp/using-mcp-in-roo

Zed

Zed ではこれらをコンテキストサーバーと呼び、キーには mcpServers ではなく context_servers を使います。設定ファイル（コマンドパレットから zed: open settings file を実行）にエントリを追加するか、Settings → AI → MCP Servers → Add Server → Add Local Server から Zed に設定を書き込ませてください。

{
  "context_servers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "mycompany16-prod-12345678"
      }
    }
  }
}

Settings → AI → MCP Servers にあるサーバー名の横のインジケータードットで、サーバーが起動したかどうかを確認できます。ツールチップに「Server is active」と表示された緑色のドットは、Zed がサーバーに接続できたことを示します。ツールの承認は agent.tool_permissions.default で制御され、デフォルトは "confirm" です。ツールごとのルールには mcp:odoo-assistant:<tool_name> の形式のキーを使います。たとえば、mcp:odoo-assistant:search_read です。

ソース：https://zed.dev/docs/ai/mcp

JetBrains AI Assistant

JetBrains AI Assistant では、設定ファイルを自分で探すのではなく、ダイアログから設定します。Settings | Tools | AI Assistant | Model Context Protocol (MCP) に移動し、Add をクリックして STDIO を選択し、次の 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_DB": "mycompany16-prod-12345678"
      }
    }
  }
}

ダイアログには command と args の説明があり、JSON の横に独自のフィールドとして Working directory と Server level が追加されます。Server level では、サーバーをグローバルに利用可能にするか、現在のプロジェクトでのみ利用可能にするかを設定します。OK をクリックしてから Apply をクリックします。これによってサーバーが起動し、Status 列に接続状態が表示されます。すでに Claude Desktop でこのサーバーを使用している場合は、代わりに Import from Claude を使うと、環境設定ブロックも含めて設定一式をインポートできます。

出典：https://www.jetbrains.com/help/ai-assistant/mcp.html

Odoo Online Production（読み取り専用の例）

Odoo Online（SaaS）でホストされている本番インスタンスに接続する場合は、ODOO_DB を設定する必要があります。また、安全のために ODOO_MCP_ALLOW を "none" に設定してください。Claude Desktop では次のようになります。

{
  "mcpServers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "mycompany16-prod-12345678",
        "ODOO_MCP_ALLOW": "none"
      }
    }
  }
}

Odoo Online ではデータベース一覧エンドポイントが無効になっているため、それを回避するには ODOO_DB の設定が必須です。一方、ODOO_MCP_ALLOW を "none" に設定すると、エージェントが本番環境のデータを変更できなくなります。

例では省略可能な変数を省いています。インスタンスが複数のデータベースを提供している場合は ODOO_DB を設定します。uid の確認を省略するには、ログイン名（例：[email protected]）を ODOO_USER に設定します。また、ゲートのデフォルト（拒否対象の 7 つを除くすべてのメソッド）が希望どおりでない場合は、ODOO_MCP_ALLOW / ODOO_MCP_DENY を設定します。

変更履歴

各リリースでの変更内容は CHANGELOG.md に記載しています。ここに重複して記載しないことで、両者の内容に食い違いが生じないようにしています。

ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細については LICENSE ファイルをご覧ください。