MCP4Acumatica

免責事項: このプロジェクトは、独立したコミュニティ製の統合物であり、Acumatica, Inc. との提携、承認、サポートを受けていません。 「Acumatica」は Acumatica, Inc. の登録商標です。Acumatica の名称および API の使用は、相互運用を目的としたものに限ります。

リモートの Model Context Protocol（MCP）サーバーで、Claude を Acumatica ERP 2025 R2 に接続します。Cloudflare Workers 上で動作し、お使いの Acumatica インスタンスに対してユーザーごとの OAuth 認証を行います。

各ユーザーは自分の Acumatica 認証情報で認証します。そのユーザーの Acumatica ロールが、アクセスできるレコードを制御します。MCP サーバーはさらに、アクセス時に特定の Acumatica ロールを要求し、同意画面を表示し、データが AI モデルに到達する前に機密フィールドを自動的に編集します。

機能

• 49 個のツール -- 読み取り専用のルックアップ 38 個 + ユーティリティ/ディスカバリ 6 個 + スキーマ知識 4 個 + 書き込みツール 1 個（Customer の作成/更新。デフォルトでは無効）（利用可能なツール を参照）

• ユーザーごとの OAuth -- ユーザーは自分の Acumatica 認証情報（または SSO）でログインします

• ロールベースのアクセス制御 -- Acumatica のセキュリティモデルが各ユーザーの閲覧範囲を決定します

• アクセスゲート -- 指定したカナリア Generic Inquiry を読み取れるユーザーのみが接続できます（制限方法は自由に選べます。MCP Access のようなマーカーロールが推奨されます）

• 同意画面 -- ユーザーはツールにアクセスする前に、AI によるデータ処理について同意する必要があります

• 機密フィールドの自動編集 -- SSN、銀行口座、給与、その他の PII フィールドは、データがサーバーから出る前に自動的に編集されます

• レート制限 -- デフォルトでユーザーごとに同時リクエスト 3 件、毎分 40 リクエストです。どちらも管理コンソールから調整できます。すべてのスロットが埋まっているリクエストは、即座に失敗するのではなく、短時間待って空きを待ちます。拒否された場合、構造化された { error: "rate_limited", retryAfterSeconds, actionRequired } エンベロープが返され、AI にループでリトライさせるのではなく、正確に何秒待つべきかが伝えられます

• ページング拒否 -- リスト/クエリツールは、結果がレコード上限に達したとき、構造化された { truncated, paginationSupported: false, actionRequired } エンベロープを返し、ツールを再度呼び出す代わりに、より絞り込んだフィルタをユーザーに尋ねるよう AI に指示します

• 構造化監査ログ -- すべてのツール呼び出し、認証イベント、フィールド編集が記録されます

• 管理コンソール -- /docs/admin にある Web ベースの管理インターフェースで、再デプロイなしにログの閲覧とランタイム設定の管理ができます

• 長期的なログ保持 -- Cloudflare Logpush による R2 バックエンドのログストレージと、検索可能なログビューア付き

アーキテクチャ

Claude (claude.ai / Desktop / API)
    |
    v  MCP over streamable-http
+----------------------------------+
|  Cloudflare Worker               |
|  OAuth 2.1 Provider              |
|    /authorize -> Acumatica login |
|    /callback  <- Acumatica       |
|    (access gate + OIDC userinfo) |
|    /consent   -> AI data consent |
|    /token, /register (DCR)       |
|    /mcp -> McpAgent DO (49 tools)|
+---------------+------------------+
                |  Bearer token (per-user)
                v
        Acumatica 25R2 SaaS
        Contract-Based REST API
        Default/25.200.001

前提条件

• Node.js 18 以上

• Cloudflare アカウント（Durable Objects のためには Workers 有料プラン）

• 次の要件を満たす Acumatica 2025 R2 インスタンス:

  • SM303010 で Authorization Code OAuth 2.0 フロー用に構成された Connected Application（スコープはアプリ側で設定するのではなく、リクエスト内でサーバーが送信します）

  • ワーカーの /callback エンドポイントを指すリダイレクト URI

  • MCPAccess Generic Inquiry（SM208000）-- Expose via OData を有効にした簡単なカナリア GI で、ログイン時のアクセスゲートがユーザーに読み取り権限があるかを確認します（詳細は Architecture ドキュメント を参照）。GI 名は ACUMATICA_CANARY_GI で設定可能です

  • その GI を読み取れるユーザーを制限する方法 -- 許可されたユーザーにのみ割り当てたマーカー Email MCP Access ロール（SM201005）が推奨される方法です

セットアップ

インストールパスは 3 種類あります。いずれも同じ Acumatica 側の前提条件が前提です。どのパスを選ぶ場合でも、先にそちらを完了しておいてください（下記の「Acumatica 側の設定」を参照）。

パス A — Deploy to Cloudflare ボタン（ターミナル不要）

このボタンを押すと、このリポジトリがユーザーの GitHub アカウントにフォークされ、wrangler.jsonc を読み取り、KV ネームスペースと R2 バケットを自動的に作成し、シークレットの入力を求められ、デプロイされます。手順は次のとおりです。

1. ボタンをクリックします。 Cloudflare がサインイン（またはアカウント作成）と GitHub フォークの承認を求めます。

2. バインディングを確認します。 KV ネームスペースの作成を 2 回 求められます。1 回目は TOKEN_STORE バインディング（アプリデータ: トークン、OAuth ステート、キャッシュ、設定、管理セッション）、2 回目は OAUTH_KV（OAuth ライブラリが内部的に使用）です。これは想定内です。2 つの別々のバインディングであり、キーを共有することはありません。

   ⚠️ 2 つのネームスペースには 異なる 名前を付けてください（例: TOKEN_STORE は mcp4acumatica-app、OAUTH_KV は mcp4acumatica-oauth）。Cloudflare の自動プロビジョニングは Worker 名からデフォルトのタイトルを生成するため、両方のフィールドがデフォルトで mcp4acumatica になります。これは、同じタイトルで 2 つのネームスペースを作成すると失敗します（"Cannot provision a KV Namespace with the title … because it already exists." というエラーが表示されます）。すでにこのエラーが出た場合は、中途半端なネームスペースが残っています。Storage & Databases → KV に移動して、孤立した mcp4acumatica ネームスペースを削除し、2 つの異なる名前で再試行してください。（Cloudflare の GUI の自動プロビジョニングでは、両方のバインディングを 1 つのネームスペースに割り当てることはできず、設定ファイルで異なるタイトルを事前に設定することもできません。正しい方法は、異なる名前の別々のネームスペースを 2 つ作ることです。GUI が失敗し続ける場合は、以下のターミナルでのインストールパスを使用してください。setup.sh は 1 つのネームスペースを作成して、両方のバインディングをそれにバインドします）。

   R2 バケット（mcp4acumatica-logs、mcp4acumatica-index）も同じタイミングで作成されますが、名前は wrangler.jsonc で固定されているため衝突しません。

3. シークレットを設定します。 求めに応じて、次を貼り付けます:

   • ACUMATICA_CLIENT_ID -- 自分の Connected Application（SM303010）から

   • ACUMATICA_CLIENT_SECRET -- 同じ画面から

   • COOKIE_ENCRYPTION_KEY -- 任意のページでブラウザのコンソールを開き、次を実行します:

     [...crypto.getRandomValues(new Uint8Array(32))].map(b => b.toString(16).padStart(2,'0')).join('')

     生成された 64 文字の 16 進数文字列をコピーします。

   • ADMIN_SECRET -- 自分が覚えていられる任意のパスワード（/docs/admin コンソールを保護します）。希望がなければ、[...crypto.getRandomValues(new Uint8Array(24))].map(b => b.toString(16).padStart(2,'0')).join('') などで生成してください。

4. デプロイします。 Cloudflare がフォークを Workers ビルドに接続し、最初のデプロイをプッシュします。

5. Acumatica の変数を更新します。 デプロイ完了後、Cloudflare ダッシュボードで Workers & Pages → mcp4acumatica → Settings → Variables and Secrets を開いて編集します:

   • ACUMATICA_URL（例: https://yourcompany.acumatica.com）

   • ACUMATICA_TENANT（ログイン会社）

   • 必要に応じて ACUMATICA_MAX_RECORDS、ACUMATICA_CANARY_GI、REDACT_PATTERNS、REDACT_SKIP Save and Deploy をクリックします -- Cloudflare は新しい値で再デプロイします。

6. Connected Application にリダイレクト URI を追加します。 ワーカーは https://mcp4acumatica.<your-account>.workers.dev でアクセスできるようになりました。Acumatica の SM303010 画面のリダイレクト URI に https://<that-host>/callback を追加します。（代わりにカスタムドメインを使用する場合は、以下の「カスタムドメイン」を参照してください。）

7. デプロイをテストします。 https://<your-host>/docs/admin/preflight にアクセスし、ADMIN_SECRET でログインして、preflight 診断を実行します。Acumatica への接続、OIDC ディスカバリエンドポイント、Connected App の資格情報、テナントパス、コントラクト API バージョンを検出します。設定不具合があれば、名前を挙げて指摘されます。

この時点で、Claude を接続できます（下記「Claude を接続する」を参照）。

パス B — ワンライナーインストーラー（ターミナル）

既に git、node、npm があれば、次を実行します:

curl -fsSL https://mcp4acumatica.hallboys.com/install.sh | bash

これは、リポジトリをクローンして依存関係をインストールし、./setup.sh を実行します。セットアップスクリプトは、ユーザーが指定する必要がある Acumatica の値（URL、テナント、Connected App のクライアント ID とシークレット）を求め、暗号化シークレットを自動生成し、KV 名前空間と R2 バケットを作成して、シークレットをアップロードし、デプロイしてから、preflight チェックを実行します。

スクリプトを先に確認したい場合は:

curl -fsSL https://mcp4acumatica.hallboys.com/install.sh -o install.sh
less install.sh   # read it
bash install.sh   # then run

パス C — 手動セットアップ（ターミナル）

1. クローンとインストール

git clone https://github.com/hallboys/MCP4Acumatica.git
cd MCP4Acumatica
npm install

2. KV 名前空間を作成する

npx wrangler kv namespace create TOKEN_STORE

出力のネームスペース ID をメモしてください ― 次に wrangler.jsonc に貼り付けます。同じ ID が TOKEN_STORE と OAUTH_KV の両方のバインディングに使用されます。

3. wrangler を設定する

wrangler.jsonc は、リポジトリにデプロイテンプレートとして保管されています。その場で直接編集して、次の項目を入力します:

• 手順 2 の KV ネームスペース ID（TOKEN_STORE と OAUTH_KV の両方のバインディング ― どちらも同じ ID）

• ACUMATICA_URL — お使いの Acumatica インスタンスの URL（例: https://yourcompany.acumatica.com）

• ACUMATICA_TENANT — お使いの Acumatica の会社名/テナント名

ローカルの値を git status に出さないようにする（それでも引き続き競合なく更新を取得できるようにする）には:

git update-index --skip-worktree wrangler.jsonc

4. シークレットを設定する

npx wrangler secret put ACUMATICA_CLIENT_ID
npx wrangler secret put ACUMATICA_CLIENT_SECRET
npx wrangler secret put COOKIE_ENCRYPTION_KEY      # use `openssl rand -hex 32`
npx wrangler secret put ADMIN_SECRET                # any password — protects /docs/admin

5. デプロイする

npx wrangler deploy

6. ローカル開発（任意）

cp .dev.vars.example .dev.vars
# Edit .dev.vars with your Acumatica credentials
npx wrangler dev

Acumatica 側の設定

これらの手順は、選択したインストールパスに関係なく必要です。自動化することはできません ― Acumatica の API にはこれらの操作は用意されていないためです。

Connected Application (SM303233)

1. Acumatica で: System > Integration > Connected Applications (SM303010) を開く。

2. 新しい Connected Application を作成する。

3. OAuth 2.0 フローを Authorization Code に設定する。

4. リダイレクト URI を追加する: https://<your-worker-url>/callback（*.workers.dev ホスト名またはカスタムドメインを使用します）。

5. Client ID と Client Secret を記録します ― デプロイ時にシークレットとして提供します。

ここで設定するスコープフィールドはありません。OAuth スコープ（api openid profile email offline_access で、Acumatica がリフレッシュトークンを発行する offline_access を含む）は、Connected Application ではなく、MCP サーバーが認可リクエストで送信します。

アクセスゲート: カナリア Generic Inquiry (SM208000, SM201005)

ユーザーが AI ツールにアクセスする前に、ログインフローは アクセスゲート を実行します。OData を介して簡単なカナリア Generic Inquiry と照合し、ユーザーのトークンで読み取れるかどうかを確認します（200 → 許可、403 → 拒否）。サーバーは Acumatica のロールのメンバーシップを検査しません ― 「この 1 つの GI が見えるか？」とだけ問いかけます。カナリア情報を誰が読めるかは、使用シーンに自由に制限できます。セキュリティ的に最も推奨されるのはマーカーロールです。

1. カナリア GI を作成します: System > Customization > Generic Inquiry (SM208000) で、任意の簡単なクエリ（どのテーブルの 1 列でも可）で MCPAccess という GI を作成します。Expose via OData を有効にします。

2. 誰が読めるかを制限する（推奨: マーカーロール）: System > Access Rights > User Roles (SM201005) で、MCP Access というロールを作成し（スクリーン権限なしのロール）、MCPAccess GI をそのロールにのみ割り当てます。そのロールを、AI アシスタントへのアクセスを許可する各ユーザーに割り当てます。GI への OData 読み取りアクセスを制御する他の仕組みでも構いません。

カナリア GI 名は ACUMATICA_CANARY_GI 変数（デフォルト MCPAccess）で設定できます。Cloudflare ダッシュボードの Variables and Secrets または wrangler.jsonc で編集します。

Generic Inquiry の AI への公開（強く推奨）

成熟したAcumaticaインスタンスには、数百件ものGeneric Inquiryが存在することがあります。その大半は人間向けの画面（広い高度なレポートグリッド、ダッシュボード、アドホッククエリ）のために構築されています。そのすべてをアシスタントに公開するとコンテキストが膨れ上がり、誤ったインシを選んでしまいます。さらに悪いことに、OData経由で公開されたパラメータ付きGIは、静かに誤ったデータを返します: パラメータを指定せずにクエリすると、Acumaticaはエラーなしでデフォルトの（フィルタリングされていない）行を返すため、モデルはその誤りを検知できません。GI公開ゲートはこれをオプトイン方式に切り替えます。つまり、AIエージェントがクエリするのに真に有用であるかつ正しいGIにタグを付け（ExposedToMCP）、モデルはそれらのGIだけを見るようになります。

このゲートは、設定するまでは無効です。サーバーは動作しますが、レジストリがない場合、アシスタントはGIを検出できません（acumatica_list_general_inquiries は何も返さず、利用者が正確な名前を指定すればGIを実行することはできます）。設定すると、アシスタントには安全に検出できる精選されたGIセットが提供されます。有効化には、Acumaticaのカスタマイズプロジェクトが一度だけ必要です。acumatica/ に同梱されたプロジェクトは、カスタムフィールド UsrExposedToMCP / UsrAIDescription（GIDesign）と UsrResAIDescription（GIResult）、さらにSM208000フォームの変更を追加するもので、続けて MCPGIs / MCPGIFields フィードGIの作成、MCP Access ロールへのフィード読み取り権限の付与、公開したいGIへのタグ付けを行います。詳細は docs/generic-inquiries.md を参照してください。

完全な理由、公開するGIの選定方法、手順を追ったセットアップについては、Generic Inquiries を参照してください。

カスタムドメイン（任意）

デプロイすると、最初から*.workers.devのホスト名が使えるようになります。ブランドを付けたホスト名を割り当てるには:

• Cloudflareダッシュボードを使用する場合: Workers & Pages → mcp4acumatica → Settings → Domains & Route → 追加 を選択します。ドメインのゾーンがCloudflareアカウントに存在している必要があります。

• wrangler.jsonc を使用する場合: ファイル先頭の routes ブロックToコメントを外し、pattern と zone_name を編集して再デプロイします。

ホスト名を変更した場合は、接続アプリ（SM303010）のリダイレクト URI に新しい https://<host>/callback を追加することを忘れないでください。

Claude との接続

Claude.ai / Claude Desktop

1. 設定 > コネクタ に移動します。

2. コネクタを追加 をクリックし、URL として https://<your-worker-url>/mcp を入力します。

3. 最初の使用時に、Acumatica のログインページへリダイレクトされます。

4. アカウントがカナリアGIを読み取れる場合（つまりアクセス権が付与されている場合）、AIデータ処理について説明する同意ページが表示されます。

5. 同意を確認すると、Claude は全 49 ツールにアクセスできるようになります。

Claude Code (CLI)

claude mcp add acumatica-erp --transport streamable-http https://<your-worker-url>/mcp

API（Anthropic SDK を利用する場合）

Anthropic API を MCP で利用する場合は、MCP クライアントを https://<your-worker-url>/mcp にポイントします。サーバーは、/register での Dynamic Client Registration に対応した OAuth 2.1 をサポートしています。

利用可能なツール

コア

財務 / 会計

在庫 / 倉庫

調達

プロジェクト

サービス / フィールド

営業 / CRM

配送 / フルフィルメント

人事 / 給与

CRMアクティビティ

ユーティリティ / 探索

ヒント: まず acumatica_describe_entity で利用可能なフィールドを確認してから、acumatica_list_entities で検索・フィルターをかけることを推奨します。Generic Inquiry の場合は、acumatica_list_generic_inquiries でGI名に検索し、acumatica_describe_inquiry で利用可能なフィールドを確認します。利用パターンは docs/example-prompts.md にあります。

ドキュメント

詳細なドキュメントは docs/ フォルダにあります:

• Tool Reference -- 全49ツールの完全仕様（パラメータとエンドポイント）。

• Example Prompts -- Claude および他のMCPクライアント向けのプロンプト例（ユースケース別にまとめたもの）。

• OData Filtering Guide -- $filter, $orderby, $select, $expand, $top クエリパラメータのガイド。

• Generic Inquiries -- GIが AI 利用でゲートされる理由、公開すべきGIの選定方法、オプトインのレジストリの有効化方法。

• Schema Knowledge -- 統合・カスタマイゼーションのためのオfffieスキーマ探索ツールとスキーマインデックスの構築方法。

• Architecture -- 詳細なアーキテクチャ、OAuthフロー、セキュリティモデル、設計の決定。

• Self-Hosting Guide -- Cloudflare以外でNode.jsやその他のプラットフォーム上でMCPサーバーを実行する方法。

• Upgrading Acumatica -- 接続先のAcumaticaバージョンを変更・アップグレードする際の手続き。

スキル

このリポジトリに同梱される再利用可能なClaudeスキル（skills/）:

• acumatica-gi-descriptions -- Generic Inquiryとその結果カラム向けに、AI向けの説明文を作成するエンドツーエンドのプロセス。名前から推測するのではなく、GI自体の設計メタデータ（テーブル、JOIN、WHERE条件、カラム）に基づいて説明します。プラットフォーム側のトップウイヤー（GIメタデータの一括連携を黙って失敗させるもの）、探す価値のある設計シグナルのチェックリスト、トランケーション監査・設計用ブリーフ・ドラフト検証のための3種のスクリプトが含まれます。

使用するには、Claude にスキルディレクトリを指定するか、自分の .claude/skills/ にコピーしてください。

セキュリティ

• 保存される認証情報はありません。 MCPサーバーはAcumaticaのパスワードを保存しません。OAuth 2.0の認可コードフローを使用します -- ユーザーはAcumaticaに直接認証します。

• ユーザーごとのトークン。 各ユーザーのAcumaticaアクセストークンは、プラットフォームのキーバリューストア（デフォルトのデプロイではCloudflare KV）に保存され、ユーザー名でスコープされます。トークンは有効期限が切れると自動的に更新されます。リフレッシュトークンの有効期限が切れた場合も、手動での再接続を必要とせず、接続が自動的に再認証されます。

• アクセスゲート。 指定されたカナリアGeneric Inquiryを読み取れるユーザーのみが接続できます。サーバーはログイン時にOData経由でGIの読み取り可否をチェックします（ロールのメンバーシップではなく）。アクセス権のないユーザーにはアクセス拒否ページが表示されます。GIの制限は自由に設定できます -- マーカーとしてMCP Accessロールを使う方法が推奨されます。GI名はACUMATICA_CANARY_GIで設定できます。

• 同意確認。 アクセスチェックを通過したユーザーは、MCPセッションが起動する前に、自分のデータが外部AIモデルによって処理されることに同意する必要があります。

• 機密フィールドの秘匿。 ツールのレスポンスは自動的にスキャンされ、機密フィールド名（SSN、銀行口座、給与、クレジットカードなど）に一致した値は[REDACTED]に置き換えられます。パターンは環境変数REDACT_PATTERNSとREDACT_SKIPで設定できます。

• ロールベースのアクセス。 ユーザーのAcumaticaロールによって読み取れるレコードが決まります。Acumatica内でそのレコードへのアクセス権がないユーザーは、MCPサーバー経由でもアクセスできません。

• 読み取り専用。 現在のすべてのツールは読み取り専用のルックアップです。データは作成・変更・削除されません。

• レート制限。 デフォルトは同時リクエスト3件、1分あたり40件、クエリあたり最大1000レコードです。これらは、再デプロイせずに、管理コンソールの/docs/admin/settingsからすべて設定できます。制限はユーザーごとで、AcmaticaへのHTTP呼び出し（ツール呼び出しではなく）をカウントします。拒否されたリクエストは、正確なretryAfterSecondsを含む構造化エンベロープを返し、rate_limit_hitイベントとしてログに記録されるため、上限が厳しすぎるかどうかを判断できます。

• ページネーション拒否。 LIST/クエリツール（acumatica_list_entities、acumatica_run_inquiry、acumatica_list_generic_inquiries）はページネーションをサポートしていません。レスポンスがACUMATICA_MAX_RECORDSに達すると、ツールは構造化エンベロープ（truncated: true、paginationSupported: false、actionRequired: "..."）を返し、さらにレコードを取得するのではなく停止して、ユーザーに絞り込んだフィルタを依頼するようAIに指示します。

• 監査ログ。 すべてのツール呼び出し、認証イベント（ログイン成功・拒否、同意の受諾）、フィールド秘匿イベントが構造化JSONで記録されます。表示にはnpx wrangler tailを使用します。

プラットフォームの可搬性

デフォルトのデプロイはCloudflare Workersを対象としていますが、ツールハンドラとコアライブラリはプラットフォーム非依存です。ストレージ抽象化（IKeyValueStore インターフェース + AppEnv 型）によって、ツールロジックがCloudflare固有のAPIから分離され、Node.js上でRedis、SQLite、その他のストレージバックエンドを使用するセルフホストメントデプロイが可能になります。詳細はSelf-Hosting Guideを参照してください。

技術スタック

• ランタイム: Cloudflare Workers + Durable Objects

• MCP: agents SDK (McpAgent)、@modelcontextprotocol/sdk

• 認証: @cloudflare/workers-oauth-provider

• HTTPルーティング: Hono

• 言語: TypeScript

• 検証: Zod

開発

npx wrangler dev       # Start local dev server
npx tsc --noEmit       # Type check
npx wrangler tail      # Stream live logs from deployed worker

ライセンス

Apache 2.0 -- Copyright 2026 Hall Boys, Inc.