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 个写入工具（客户创建/更新，默认禁用）（参见可用工具）

• 每用户 OAuth —— 用户使用他们的 Acumatica 凭据（或 SSO）登录

• 基于角色的访问 —— Acumatica 的安全模型控制每个用户能看到的内容

• 访问门控 —— 只有能够读取指定的金丝雀通用查询的用户才能连接（你可以按自己的方式限制它；推荐使用标记角色，如 MCP Access）

• 同意中间页 —— 用户必须确认 AI 数据处理后才能访问工具

• 敏感字段编辑 —— 社会安全号码、银行账户、薪资及其他个人身份信息字段在数据离开服务器前会自动被编辑

• 速率限制 —— 默认每个用户 3 个并发请求和每分钟 40 个请求，可在管理控制台调整。当所有槽位都被占满时，请求会短暂等待一个槽位而非直接失败，拒绝时返回一个结构化的 { error: "rate_limited", retryAfterSeconds, actionRequired } 信封，告诉 AI 确切需要等待的时间，而不是循环重试

• 分页拒绝 —— 当结果达到记录上限时，列表/查询工具返回一个结构化的 { truncated, paginationSupported: false, actionRequired } 信封，指示 AI 要求用户提供更窄的过滤器，而不是再次调用该工具

• 结构化审计日志 —— 所有工具调用、认证事件和字段编辑都有日志记录

• 管理控制台 —— 位于 /docs/admin 的基于 Web 的管理界面，用于查看日志和管理运行时设置，无需重新部署

• 长期日志保留 —— 通过 Cloudflare Logpush 将日志存储在 R2 中，并带有可搜索的日志查看器

Related MCP server: MCP4Acumatica

架构

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 账户（需要 Workers 付费计划以支持 Durable Objects）

• 一个 Acumatica 2025 R2 实例，且满足以下条件：

  • 在 SM303010 中配置了一个已连接应用程序，使用授权码 OAuth 2.0 流程（作用域由服务器在请求中发送，而非在应用程序上配置）

  • 将一个重定向 URI 指向你的 worker 的 /callback 端点

  • 一个 MCPAccess 通用查询（SM208000）—— 一个简单的金丝雀 GI，启用通过 OData 公开；登录访问门控检查用户是否能读取该 GI（详见架构文档）。GI 名称可通过 ACUMATICA_CANARY_GI 配置。

  • 一种限制谁能读取该 GI 的方法——建议使用一个仅分配给允许用户的标记**MCP Access 角色**（SM201005）

设置

有三种安装路径。所有三种路径都依赖于相同的 Acumatica 侧前提条件 —— 无论选择哪种路径，请先完成这些步骤（参见下方的“Acumatica 侧配置”）。

路径 A — 一键部署到 Cloudflare 按钮（无需终端）

该按钮将此仓库 fork 到你的 GitHub 账户，读取 wrangler.jsonc，自动创建 KV 命名空间和 R2 存储桶，提示输入密钥，然后部署。逐步说明：

1. 点击按钮。 Cloudflare 将要求你登录（或创建账户）并授权一个 GitHub fork。

2. 确认绑定。 系统会提示你两次创建 KV 命名空间——一次用于 TOKEN_STORE 绑定（应用数据：令牌、OAuth 状态、缓存、配置、管理会话），另一次用于 OAUTH_KV（由 OAuth 库内部使用）。这是预期的：它们是两个独立的绑定，从不共享键。

   ⚠️ 给这两个命名空间起不同的名称（例如，TOKEN_STORE 使用 mcp4acumatica-app，OAUTH_KV 使用 mcp4acumatica-oauth）。Cloudflare 的自动配置会根据 Worker 名称派生默认标题，因此两个字段默认都是 mcp4acumatica——如果创建两个同名命名空间会失败，出现 “Cannot provision a KV Namespace with the title … because it already exists.” 如果你已经遇到这个错误，说明留下了一个未完成的命名空间：前往存储与数据库 → KV，删除孤立的 mcp4acumatica 命名空间，然后用两个不同的名称重试。（Cloudflare 的 GUI 自动配置无法将两个绑定指向同一个命名空间，而配置也无法预设不同的标题——因此使用两个不同名称的独立命名空间是正确的方式。如果 GUI 一直失败，请使用下方的终端安装路径：setup.sh 会创建一个命名空间并将两个绑定都指向它。）

   R2 存储桶（mcp4acumatica-logs、mcp4acumatica-index）以相同方式创建，但它们的名称在 wrangler.jsonc 中是固定的，因此不会冲突。

3. 设置密钥。 在提示时粘贴：

   • ACUMATICA_CLIENT_ID —— 来自你的已连接应用程序（SM303010）

   • ACUMATICA_CLIENT_SECRET —— 来自同一屏幕

   • COOKIE_ENCRYPTION_KEY —— 在任何页面上打开浏览器控制台并运行：

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

     复制生成的 64 字符十六进制字符串。

   • ADMIN_SECRET —— 任何你会记住的密码（保护 /docs/admin 控制台）。如果你没有偏好，可以使用 [...crypto.getRandomValues(new Uint8Array(24))].map(b => b.toString(16).padStart(2,'0')).join('') 生成一个。

4. 部署。 Cloudflare 将 fork 连接到 Workers Builds 并推送首次部署。

5. 更新 Acumatica 变量。 部署完成后，在 Cloudflare 仪表板中打开 Workers 与 Pages → mcp4acumatica → 设置 → 变量和密钥，并编辑：

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

   • ACUMATICA_TENANT（你的登录公司）

   • 可选地 ACUMATICA_MAX_RECORDS、ACUMATICA_CANARY_GI、REDACT_PATTERNS、REDACT_SKIP 点击保存并部署——Cloudflare 将使用新值重新部署。

6. 向你的已连接应用程序添加重定向 URI。 你的 worker 现在可以通过 https://mcp4acumatica.<your-account>.workers.dev 访问。将 https://<that-host>/callback 添加到 Acumatica 的 SM303010 屏幕中的重定向 URI 中。（要使用自定义域名，请参见下方的“自定义域名”）。

7. 测试部署。 访问 https://<your-host>/docs/admin/preflight，用你的 ADMIN_SECRET 登录，然后运行预检诊断。它会探测 Acumatica 连接、OIDC 发现端点、已连接应用凭据、租户路径和合约 API 版本——任何配置错误都会被指名道姓地指出。

之后，Claude 就可以连接了（参见下方的“连接 Claude”）。

路径 B — 一行安装器（终端）

如果你已经安装了 git、node 和 npm，运行：

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

这会克隆仓库、安装依赖项并运行 ./setup.sh。设置脚本会提示你输入必须提供的 Acumatica 值（URL、租户、已连接应用的客户端 ID 和密钥），自动生成加密密钥，创建 KV 命名空间和 R2 存储桶，上传密钥，部署，然后运行预检检查。

如果你想先查看脚本：

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 不暴露它们。

已连接应用程序（SM303010）

1. 在 Acumatica 中：系统 > 集成 > 已连接应用程序（SM303010）。

2. 创建一个新的已连接应用程序。

3. 将 OAuth 2.0 流程 设置为授权码。

4. 添加一个重定向 URI：https://<your-worker-url>/callback（使用 *.workers.dev 主机名或你的自定义域名）。

5. 记下客户端 ID 和客户端密钥——你将在部署期间将这些作为密钥提供。

此处没有要配置的作用域字段。OAuth 作用域（api openid profile email offline_access，包括使 Acumatica 颁发刷新令牌的 offline_access）由 MCP 服务器在授权请求中发送——它们不在已连接应用程序上设置。

访问门控：金丝雀通用查询（SM208000、SM201005）

在用户能够访问 AI 工具之前，登录流程会运行一个访问门控：它通过 OData 查询一个简单的金丝雀通用查询，并检查用户的令牌是否能读取该 GI（200 → 允许，403 → 拒绝）。服务器从不检查 Acumatica 角色成员身份——它只问“你能看到这个 GI 吗？”。你可以按照你的安全模型偏好来限制谁能读取金丝雀 GI；推荐使用标记角色，这是最整洁的方式。

1. 创建金丝雀 GI： 系统 > 自定义 > 通用查询（SM208000） → 创建一个名为 MCPAccess 的 GI，并设置任何简单的查询（任何表单中的单个列即可）。启用通过 OData 公开。

2. 限制谁能读取它（推荐：一个标记角色）： 系统 > 访问权限 > 用户角色（SM201005） → 创建一个名为 MCP Access 的角色，不分配任何屏幕权限，仅将 MCPAccess GI 分配给该角色，然后将该角色分配给每个应具有 AI 助手访问权限的用户。任何其他控制对 GI 的 OData 读取访问的机制也同样有效。

金丝雀 GI 的名称可通过 ACUMATICA_CANARY_GI 变量配置（默认 MCPAccess）。在 Cloudflare 仪表板（变量和密钥）或 wrangler.jsonc 中编辑它。

将通用查询暴露给 AI（强烈推荐）

成熟したAcumaticaインスタンスには、数百もの汎用照会（Generic Inquiry）が存在する可能性があり、そのほとんどは人間向けの画面（広いレポートグリッド、ダッシュボード、アドホッククエリ）用に構築されています。これらすべてをアシスタントに公開すると、コンテキストが過多になり、誤った照会を選択する原因となります。さらに悪いことに、パラメータ化されたGIをOData経由で公開すると、警告なしに誤ったデータが返されます。パラメータなしでクエリを実行すると、Acumaticaはエラーを出さずにデフォルト/フィルタリングされていない行を返し、モデルはそれを検出できません。GI公開ゲートはこれをオプトイン方式に変更します。AIエージェントがクエリするのに本当に有用で正しいGIにタグを付け（ExposedToMCP）、モデルはそれらのみを認識します。

このゲートは、設定するまで無効です。サーバーは動作しますが、レジストリがないためアシスタントはGIを検出できません（acumatica_list_generic_inquiriesは何も返さず、ユーザーは正確な名前でGIを実行することは可能です）。設定することで、アシスタントは安全に検出できる厳選されたセットを利用できるようになります。有効化は、1回限りのAcumaticaカスタマイゼーションプロジェクトです。acumatica/にバンドルされており、カスタムフィールドUsrExposedToMCP / UsrAIDescription（GIDesign）とUsrResAIDescription（GIResult）、およびSM208000フォームの変更が追加されます。その後、MCPGIs / MCPGIFieldsフィードGI、MCP Accessロールに対するフィードの読み取りアクセス、公開したいGIへのタグ付けが必要です。docs/generic-inquiries.mdを参照してください。

完全な根拠、公開するGIの決定方法、およびステップバイステップのセットアップについては、**汎用照会**を参照してください。

カスタムドメイン（オプション）

デプロイにより、標準で*.workers.devのホスト名が提供されます。ブランド化されたホスト名を追加するには：

• Cloudflareダッシュボード経由： Workers & Pages → mcp4acumatica → Settings → Domains & Routes → Add。ドメインのゾーンはCloudflareアカウント上にある必要があります。

• wrangler.jsonc経由： ファイル上部のroutesブロックのコメントを解除し、patternとzone_nameを編集して、再デプロイします。

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

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での動的クライアント登録を備えたOAuth 2.1をサポートしています。

利用可能なツール

コア

財務 / 会計

在庫 & 倉庫

購買

プロジェクト

サービス & フィールド

販売 & CRM

出荷 & フルフィルメント

人事 & 給与

CRM活動

ユーティリティ / 検出

ヒント： まずacumatica_describe_entityを使用して利用可能なフィールドを検出し、次にacumatica_list_entitiesを使用して検索/フィルタリングします。汎用照会の場合は、acumatica_list_generic_inquiriesを使用してGI名を見つけ、acumatica_describe_inquiryを使用して利用可能なフィールドを確認します。使用パターンについてはdocs/example-prompts.mdを参照してください。

ドキュメント

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

• ツールリファレンス -- パラメータとエンドポイントを含む49のツールすべての完全な仕様

• プロンプト例 -- ユースケース別に整理されたClaudeおよびその他のMCPクライアント向けのプロンプト例

• ODataフィルタリングガイド -- $filter、$orderby、$select、$expand、$topクエリパラメータのガイド

• 汎用照会 -- GIがAI使用のためにゲートされる理由、公開するGI、およびオプトインレジストリを有効にする方法

• スキーマ知識 -- 統合/カスタマイゼーション構築のためのオフラインスキーマ検出ツールと、スキーマインデックスの構築方法

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

• セルフホスティングガイド -- Cloudflare以外のNode.jsまたはその他のプラットフォームでMCPサーバーを実行する方法

• Acumaticaのアップグレード -- 接続されたAcumaticaバージョンを変更またはアップグレードする際の手順

スキル

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

• acumatica-gi-descriptions -- 汎用照会とその結果列に対するAI向け説明を作成するためのエンドツーエンドプロセス。名前から推測するのではなく、GI自身の設計メタデータ（テーブル、結合、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）から設定可能です。制限はユーザーごとで、AcumaticaへのHTTP呼び出し（ツール呼び出しではない）をカウントします。拒否された場合は、正確なretryAfterSecondsを含む構造化されたエンベロープが返され、rate_limit_hitイベントとしてログに記録されるため、制限が厳しすぎるかどうかを判断できます。

• ページネーション拒否。 リスト/クエリツール（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から切り離され、Redis、SQLite、その他のストレージバックエンドを使用したNode.jsでのセルフホストデプロイメントが可能になります。詳細はセルフホスティングガイドを参照してください。

技術スタック

• ランタイム: 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.