Odoo MCP

Odoo MCP

odoo-mcp は Odoo Enterprise 向けのワークフローにネイティブな MCP サーバーです。読み取り専用の機能検出、試算表レポート、売掛金・買掛金の経過期間別レポート、現金出納帳の確認、未照合の銀行明細行の検出、提案のみの銀行照合機能を提供します。また、正確な期間、バッチ、給与明細、従業員、給与規則、給与作業項目に関する範囲を限定した読み取り専用の給与データも提供し、決定論的な給与比較と異常レビューにも対応します。

初期の会計リリースでは、請求書、仕入先請求書、クレジットノート、支払い登録、手動仕訳のワークフローにも対応しています。変更を伴うツールはデフォルトでプレビューのみとなり、実行と冪等性の明示的な指定が必要です。

内部の Odoo アダプターは、会計および給与ワークフロー向けに、範囲を限定した型付きの会社スコープ付きプリミティブを提供します。固定されたモデル／アクションの許可リストを適用し、許可されていないフィールドを除去して、日付、10進数、リレーション、カーソルページを正規化します。また、Odoo の認証、権限、トランスポートのエラーを安全なエラーに変換します。汎用 CRUD や Odoo の設定画面は公開しません。

接続先として対応しているのは Odoo.sh とセルフホストの Odoo Enterprise です。

• Odoo 18 は外部 JSON-RPC 経由
• Odoo 19 は JSON-2 経由

その他の Odoo バージョン、Odoo Online、Community エディション、カスタムフォークには対応していません。このパッケージは Odoo モジュールではなく、汎用のモデル CRUD も公開しません。

インストール

製品名とコマンド名は odoo-mcp です。PyPI のディストリビューション名は odoo-erp-mcp です。odoo-mcp のディストリビューション名は別のプロジェクトが所有しているためです。

pipx install odoo-erp-mcp
odoo-mcp --help

このパッケージは、MCP Registry クライアント向けの互換性ランチャーとして odoo-erp-mcp も公開しています。odoo-mcp と同じサーバーを起動します。

ローカル開発

Python 3.11 以降と uv が必要です。

Copy-Item .env.example .env.local
# Replace the placeholders in .env.local, then:
uv sync --locked --all-extras
uv run odoo-mcp --profile local --config config/config.example.yaml

ローカル開発では stdio を使用します。プロセス環境の設定は .env.local より優先されます。.env.local をコミットしないでください。

リモートプロファイル

Dedicated Remote と Shared Hosted は、Local Development と同じサーバー、レジストリ、ワークフロー、Odoo アダプターを使用し、Streamable HTTP 経由で公開します。

uv run odoo-mcp --profile dedicated --host 127.0.0.1 --port 8000
uv run odoo-mcp --profile shared --host 127.0.0.1 --port 8000

Dedicated Remote は、プロセス環境から単一の Odoo 接続を読み込みます。.env.local は読み込みません。すべての /mcp リクエストに、デプロイメントから発行された HS256 ベアラ JWT が必要です。MCP のルーティング前に、サーバーは署名、固定の発行者、固定のオーディエンス、有効期限、発行時刻、サブジェクト、クライアント ID を検証します。権限と会社へのアクセス許可は、引き続きサーバー側で管理されます。ODOO_MCP_AUTH_ISSUER、ODOO_MCP_AUTH_AUDIENCE、およびシークレットストアから提供される32文字以上の ODOO_MCP_AUTH_SIGNING_KEY を設定してください。

Shared Hosted は、同じイメージ内で実行できる、オープン登録方式のアプリケーションです。OAuth のディスカバリー、動的クライアント登録、認可、トークン発行、失効、ブラウザーによる登録、保護リソースのメタデータ、MCP ルートを提供します。アプリケーションは各 Odoo 接続を検証し、Odoo から返された会社の中からユーザーが選択できるようにして、認証情報を暗号化して保存し、すべてのトークンを有効なコネクター1つにのみバインドします。.env.shared.example を基に設定してください。バージョン管理された256ビットの暗号化キーは、運用者が管理するシークレットストアから取得する必要があります。設定の欠落、無効な暗号文、無効なアクセス許可、安全でない Odoo 接続先、認可されていないコネクターバインドがある場合は、すべてフェイルクローズします。Shared Hosted は、永続的なローカル SQLite ボリュームを持つ書き込み可能な単一プロセス、または接続プールを使用するランタイム接続と直接接続のマイグレーション用接続を備えた、要件を満たす PostgreSQL のいずれかに対応しています。TLS、パブリックイングレス、モニタリング、本番環境へのデプロイメントは、引き続き運用者の責任です。

再現可能な Dedicated Remote の Docker および systemd テンプレート、Shared Hosted の統合要件、ネットワークの強化に関するガイダンスについては、docs/deployment.md を参照してください。サンプルの HTTP リスナーをパブリックインターネットに直接公開しないでください。

永続状態

odoo_mcp.storage.Storage は、監査記録、提案、アーティファクト、冪等性予約、機能スナップショット、暗号化された Shared Hosted 接続を対象に、順序付きの SQLite および PostgreSQL マイグレーションとテナント単位のリポジトリを提供します。監査行は追記専用で、テナントごとに SHA-256 ハッシュチェーンを形成します。冪等性予約は、テナント、会社、ツール、キー、リクエストペイロードを 24 時間の再実行に紐付けます。一方、処理中および結果不明の状態は、明示的な復旧が行われるまでブロックされます。最終結果には、再実行可能なレスポンスを保持し、予約時の会社と一致させる必要があります。監査の失敗テキストは、登録済みのエラーコードから生成されます。自由形式の上流エラーテキストは永続化されません。

SQLite のバックアップでは、一貫性のあるスナップショットを使用します。復元先には新しい場所を指定します。データベースの整合性、マイグレーション、テナントの監査チェーン、冪等性状態、機能データ、暗号化された接続の検証に合格した場合にのみ復元が受け入れられます。暗号化キーは別途バックアップし、復元する必要があります。PostgreSQL ではデータベースレベルでマイグレーションを直列化し、リポジトリ、OAuth、監査、冪等性、暗号化、ライフサイクルに関する同じ契約を維持します。

サーバーは、デフォルトで .odoo-mcp/state.sqlite3 にローカルの永続状態を保存します。別の SQLite ファイルを選択するには、--storage <path> を使用します。成功した会計レポートは、Markdown アーティファクトと簡潔な監査結果をアトミックに永続化します。分離 ID が解決されている場合、失敗または拒否されたレポート呼び出しでは、機密情報を含まない失敗監査が永続化されます。

書き込みの安全性

odoo_mcp.policy.WriteSafetyCoordinator は、書き込み可能なワークフローに必須の境界です。ワークフローの準備前に、レジストリのリスクメタデータ、解決済み ID、権限、会社、機能の各ゲートを適用します。呼び出しはデフォルトでプレビューのみです。実行には、明示的な dry_run: false と空ではない冪等性キーが必要です。その後、そのキーを予約し、試行監査を追加してから、最新状態を検証し、Odoo を変更します。

成功、拒否、競合、再実行、既知の失敗、結果不明はそれぞれ区別され、再起動後も安全に再実行できます。不確実な変更が自動で再試行されることはありません。変更が発生した可能性がある後に結果の永続化に失敗した場合、処理中の予約は重複実行を引き続きブロックします。変更が発生していないことが明らかな Odoo の権限拒否は、既知の失敗として構造化された形式で保持されます。監査テキストとレスポンステキストでは、生の例外詳細が抑制されます。

人による確認は MCP クライアントホストが担います。サーバーは承認トークンを発行せず、承認 UI も提供せず、プレビューを自動的に実行へ切り替えることもありません。照合の呼び出しはデフォルトでプレビューです。冪等性キーを指定した明示的な dry_run: false の呼び出しでは、サーバー管理の提案と Markdown アーティファクトが保存されますが、照合が確定されることも、Odoo の銀行取引明細行が変更されることもありません。

設定

Local および Dedicated Odoo の設定は .env.example に、Shared Hosted の運用者向け設定は .env.shared.example に記載されています。Odoo のバージョンは設定しないでください。アダプターがバージョンを検出し、サポート対象外のレスポンスや不正なレスポンスに対して明示的に失敗します。config/config.example.yaml は安全な MCP 権限マップの例で、現在の読み取りツールを有効にしています。ツールが許可されるのは、レジストリで定義された権限の下に記載されている場合のみです。不明なエントリーや一致しないエントリーがあると、起動が妨げられます。

必要な会社およびモジュールへのアクセス権のみを持つ、非本番環境専用の Odoo 技術ユーザーを使用してください。会社 ID は MCP の追加の認可境界であり、技術ユーザーの Odoo 権限を拡張することはありません。

会計ワークフロー

• get_currency_rate_history は、正確に指定した通貨について、選択した会社の Odoo 為替レート履歴を返します。会社固有のレートを共有レートより優先し、換算は行わずに両方のレート方向を保持します。
• get_trial_balance は、転記済みの期首残高、期間の開始日と終了日を含む借方・貸方の増減、期末残高、合計、および Markdown アーティファクトを返します。
• get_profit_and_loss は、期間の開始日と終了日を含む期間について、転記済み明細を Odoo の収益・費用勘定タイプで分類します。収益は貸方から借方を差し引き、費用は借方から貸方を差し引き、純利益は収益から費用を差し引いて算出します。
• get_balance_sheet は、終了日を含む日付までの転記済み明細を Odoo の資産・負債・資本勘定タイプで分類します。未締めの損益を資本合計の内訳として個別に報告し、会社通貨の精度で会計等式を検証します。
• get_aged_receivables と get_aged_payables は、後日の部分消込も含め、指定日時点の転記済み残高を再構成し、未到来、1～30 日、31～60 日、61～90 日、90 日超の区分に分類します。
• get_cashbook は、現金および銀行仕訳帳の転記済み仕訳明細と、期首残高、期間中の借方・貸方、期末残高を返します。
• flag_unmatched_statement_lines は、指定されたしきい値以上で、一意に特定できる有効な照合候補がない未照合の取引明細行を特定します。
• reconcile_bank_statement_lines は、金額、取引先、正規化された参照情報、日付の近さに基づいて、1 対 1 の候補をスコアリングします。同点や候補の重複使用は、明示的に未照合の結果として扱われます。このツールは提案をローカルに保存できますが、Odoo の照合は実行しません。
• list_open_invoices と list_open_bills は、後日の部分消込も含め、指定日時点のレコード通貨および会社通貨の残高を再構成します。
• create_customer_invoice と create_supplier_bill は、デフォルトでデータを変更しない、入力内容のみのプレビューを提供します。明示的に実行すると、未転記のドラフトを 1 件作成し、Odoo で確定した会計結果を読み戻します。
• create_credit_note は、元の伝票にリンクした全額取消のドラフトを 1 件作成します。転記前に validate_invoice は、残高、通貨、勘定、合計、税に関するローカルで判定可能なブロッカーを報告し、Odoo でしか確認できない転記チェックは明示的に対象外とします。
• register_payment は、ルートの検出と実行を Odoo 標準の支払登録ウィザードに委ねます。プレビューでは、範囲が限定された一時的なウィザードレコードを作成する場合がありますが、支払を実行したり会計レコードを変更したりすることはありません。手動ではない、または特定できない支払方法については、外部への影響が不明であることを報告します。実行には、冪等性キーと、再検証済みの最新ウィザードルートが必要です。
• list_journal_entries は、フィルターに一致するドラフトおよび転記済みの手動仕訳を、明細の件数を制限したうえで、不透明な継続カーソルとともに返します。create_journal_entry は貸借が一致するドラフトのみを作成し、別の post_journal_entry ツールは、明示的な実行後に既存のドラフトを再検証して 1 件転記します。

レポート結果は決定的な順序で並べられ、デフォルトの上限 100 件、最大 500 件でカーソルページネーションされます。データが空の場合は、正常な空のレポートとして扱われます。上流での拒否、タイムアウト、不正なデータ、または取得の一部失敗は、空の結果ではなく、構造化されたエラーになります。ページ分割された Markdown アーティファクトには、行の範囲、続きの有無、レポート全体の合計が明示されます。

損益計算書と貸借対照表の分析フィルターは、正確な分析アカウント ID に対する Odoo の配分率を適用します。これらのレポートでは、カスタム勘定科目表のグループ、会計年度の締めルール、連結、消去、またはローカライズ固有のレポートレイアウトを推測しません。未対応の勘定分類は推測せず、明示的にエラーとして扱います。

給与計算の証跡ワークフロー

• list_payroll_periods は、会社単位の給与明細で確認された正確な日付の組み合わせを、範囲を限定したステータス、バッチ、通貨の証跡とともに一覧表示します。
• get_payroll_batch は、指定した正確なバッチのほか、簡潔な給与明細、従業員数と状態別件数の全容、通貨別に区分された確認済みルール／カテゴリの合計を返します。
• list_payslips は、正確なバッチ、正確な期間、またはその両方に該当する給与明細の簡潔な事実を一覧表示します。get_payslip は、範囲を限定した計算済み明細、勤務日数、一時的な入力をすべて含む、指定した正確な給与明細を返します。
• get_employee_payroll_context は、指定した正確な期間に該当する従業員と契約／バージョンの証跡のみを返します。
• list_salary_rules は、対象となる給与明細の行で確認されたルールのメタデータを報告します。給与計算の設定カタログではありません。
• get_attendance_summary は、給与計算の勤務エントリを従業員、タイプ、コード、状態別に要約します。生の勤怠データは読み取らず、実際の出勤を証明するものでもありません。
• compare_payroll_periods は、重複しない2つの期間について、従業員の正確な集合、契約の事実、勤務エントリの時間数、および通貨別に区分された確認済み明細、ルール、カテゴリの合計を比較します。
• analyze_employee_payroll_change は、1人の指定した従業員について、直接確認された変化と相関関係、未解決の原因を分けて示します。
• detect_payroll_anomalies は、公開されている固定の割合しきい値と、任意のリクエスト時の modified-z-score チェックを適用します。顧客のベースラインを学習したり保持したりしません。ソースへのリンクを含む Markdown の要約はインラインで返され、アーティファクトとして保存されません。割合しきい値は 5%（strict）、10%（standard）、20%（relaxed）です。統計的チェックには比較可能な過去の値が6件以上必要で、修正 z スコアの絶対値が3.5以上である必要があります。値が不足している場合や、中央絶対偏差がゼロの場合は、利用不可として報告されます。
• explain_payslip は、Odoo が返す明細の計算結果、カテゴリ、勤務日数の証跡、契約のコンテキストを整理しますが、給与ルールのコードを評価したり、総額から手取り額への計算を再現したりはしません。
• prepare_payroll_approval_pack は、ソースへのリンクを含む合計、任意の前期間との差異、異常、例外、制限事項、推奨される人によるレビュー操作、承認チェックリストを含む、リクエスト時の JSON とインライン Markdown のレビュー用パックを返します。給与計算を承認したり、永続的なパックやワークフロー記録を作成したりすることはありません。

これらの証跡ツールには、payroll_read と、アクセス可能な Odoo Payroll 機能が必要です。読み取り専用で、リクエストに紐づくページネーションを使用し、Odoo のソース ID を返します。監査チェーンに保存されるのは、機密性のない呼び出しメタデータのみです。給与計算の応答は、アーティファクト、提案、冪等性レコード、ワークフロー状態として永続化されません。金額の比較で通貨を結合または換算することはありません。BASIC、GROSS、NET の認識済み合計には、Odoo のルールコードが完全一致するものが必要です。また、雇用主負担額は明示的に利用不可のままです。

制御された給与計算ドラフトへの書き込み

• set_draft_payroll_input は、編集可能な給与明細1件に対する対象となる一時的な入力1件について、プレビューを返すか、明示的に作成または更新します。
• remove_draft_payroll_input は、対象となる一時的な入力を指定して1件、プレビューを返すか、明示的に削除します。
• recalculate_draft_payslip は、Odoo の標準給与明細計算を個別に実行し、新しい給与明細の証跡を返します。

これらのツールには、payroll_draft_write と、アクセス可能な Odoo Payroll 機能が必要です。すべての呼び出しは、変更を行わないプレビューがデフォルトです。実行には、dry_run: false と空でない冪等性キーが必要です。完全な現在の入力状態を再確認し、給与明細ごとに書き込みを直列化します。入力を変更しても、再計算は自動的に実行されません。再計算は編集可能な給与明細に限られ、給与計算の確認、記帳、締め、支払い、その他の確定処理は実行できません。監査と再実行のために保持されるのは運用上の ID とステータスのみです。入力の説明、金額、従業員の詳細、計算済みの給与計算値は、これらの書き込みワークフローでは保存されません。

検証

1 つのコマンドで、一時ディレクトリ内のフォーマットチェック、静的解析、テスト、パッケージのビルド、成果物の検査を実行します。

uv run python scripts/verify.py

自動テストでは、Odoo の合成応答を使用します。実際の Odoo バージョンとの互換性、実際の権限、インストール済みモジュール、デプロイ時のネットワーク環境は確認できません。

ストレージのバックアップ、復元、整合性検証、監視、アップグレード、ロールバック、インシデント対応の手順については、docs/operations.md に記載しています。セキュリティ境界と脆弱性の報告については SECURITY.md を、サポート対象の構成とサポートの依頼については SUPPORT.md を参照してください。

docs/demo.md では、範囲を限定した会計デモを紹介しています。オペレーターが非本番環境の Odoo で実行を別途許可しない限り、書き込み可能なすべての呼び出しをプレビューモードのままにします。