MCP4Acumatica

免责声明： 本项目是一个独立的、社区构建的集成，与 Acumatica, Inc. 无关联、未经其认可或支持。 “Acumatica”是 Acumatica, Inc. 的注册商标。使用 Acumatica 名称和 API 仅用于互操作性目的。

一个远程 模型上下文协议 (MCP) 服务器，将 Claude 连接到 Acumatica ERP 2025 R2。运行在 Cloudflare Workers 上，通过每个用户的 OAuth 认证连接到您的 Acumatica 实例。

每个用户使用自己的 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 要求用户提供更窄的过滤器，而不是再次调用工具

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

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

• 长期日志保留 — 通过 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 流程（作用域由服务器在请求中发送，而不是在应用程序上配置）

  • 指向您 Worker 的 /callback 端点的重定向 URI

  • 一个 MCPAccess 通用查询 (SM208000) — 一个简单的金丝雀 GI，启用了 通过 OData 公开；登录访问门检查用户是否可以读取它（有关详细信息，请参见架构文档）。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 — 使用相同标题创建两个命名空间会失败，并显示 “无法使用标题 … 配置 KV 命名空间，因为它已经存在。” 如果您已经遇到该错误，则留下了一个半完成的命名空间：转到 存储和数据库 → 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 → Settings → Variables and Secrets 并编辑：

   • 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 查询一个简单的金丝雀通用查询，并检查用户的令牌是否可以读取它（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 仪表板（Variables and Secrets）或 wrangler.jsonc 中编辑它。

通用查询对 AI 的暴露（强烈推荐）

一个成熟的 Acumatica 实例可能拥有数百个通用查询，其中大部分是为人工界面构建的（宽报表网格、仪表板、即席查询）。将所有查询暴露给助手会淹没其上下文，并使其选择错误的查询——更糟糕的是，通过 OData 返回的带参数通用查询会静默返回错误数据：在没有参数的情况下查询时，Acumatica 会返回默认/未过滤的行且无错误，模型无法检测到这一点。通用查询暴露门控将其转变为选择加入机制：你标记那些对 AI 代理真正有用且正确的通用查询（ExposedToMCP），模型只会看到这些查询。

该门控在你配置之前处于非活动状态——服务器可以运行，但没有注册表，助手无法发现通用查询（acumatica_list_generic_inquiries 返回空；用户仍可通过精确名称运行通用查询）。配置后，它会为助手提供一个可以安全发现的精选集合。启用它是一次性的 Acumatica 定制化项目——打包在 acumatica/ 中，它添加了自定义字段 UsrExposedToMCP / UsrAIDescription（GIDesign）和 UsrResAIDescription（GIResult）以及 SM208000 表单更改——然后是 MCPGIs / MCPGIFields 馈送通用查询，为 MCP Access 角色授予对馈送的读取权限，并标记你想要暴露的通用查询。请参阅 docs/generic-inquiries.md。

请参阅 通用查询 了解完整原理、如何决定暴露哪些通用查询以及逐步设置。

自定义域名（可选）

部署会直接提供一个 *.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. 如果你的账户可以读取金丝雀通用查询（即你已被授予访问权限），你将看到一个解释 AI 数据处理的同意页面

5. 确认同意后，Claude 将可以访问所有 49 个工具

Claude Code（CLI）

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

API（通过 Anthropic SDK）

当通过 MCP 使用 Anthropic API 时，将 MCP 客户端指向 https://<your-worker-url>/mcp。该服务器支持在 /register 处进行带有动态客户端注册的 OAuth 2.1。

可用工具

核心

财务/会计

库存与仓库

采购

项目

服务与现场

销售与客户关系管理

运输与履行

人力资源与薪资

客户关系管理活动

实用工具/发现

提示： 首先使用 acumatica_describe_entity 发现可用字段，然后使用 acumatica_list_entities 进行搜索/过滤。对于通用查询，使用 acumatica_list_generic_inquiries 查找通用查询名称，使用 acumatica_describe_inquiry 查看可用字段。请参阅 docs/example-prompts.md 了解使用模式。

文档

详细文档位于 docs/ 文件夹中：

• 工具参考 -- 所有 49 个工具的完整规范，包含参数和端点

• 示例提示 -- 按用例组织的 Claude 和其他 MCP 客户端示例提示

• OData 过滤指南 -- $filter、$orderby、$select、$expand 和 $top 查询参数指南

• 通用查询 -- 为什么通用查询对 AI 使用进行门控、暴露哪些通用查询以及如何启用选择加入注册表

• 架构知识 -- 用于构建集成/定制化的离线架构发现工具，以及架构索引的构建方式

• 架构 -- 详细架构、OAuth 流程、安全模型和设计决策

• 自托管指南 -- 如何在 Cloudflare 之外的 Node.js 或其他平台上运行 MCP 服务器

• 升级 Acumatica -- 更改或升级连接的 Acumatica 版本时应采取的步骤

技能

此仓库附带的可复用 Claude 技能，位于 skills/：

• acumatica-gi-descriptions -- 为通用查询及其结果列编写面向 AI 描述的端到端流程，基于通用查询自身的设计元数据（表、连接、WHERE 条件、列）而非从名称猜测。包括导致批量通用查询元数据工作静默出错的平台陷阱、值得寻找的设计信号清单，以及用于截断审计、设计简报和草稿验证的三个脚本。

要使用它，将 Claude 指向技能目录，或将其复制到你自己的 .claude/skills/ 中。

安全

• 无存储凭据。 MCP 服务器不存储 Acumatica 密码。它使用 OAuth 2.0 授权码流程——用户直接通过 Acumatica 进行身份认证。

• 每用户令牌。 每个用户的 Acumatica 访问令牌存储在平台键值存储（默认部署时使用 Cloudflare KV）中，作用域限定为用户名。令牌过期时会自动刷新。如果刷新令牌过期，连接会自动重新认证，无需手动重新连接。

• 访问门控。 只有能够读取指定哨兵通用查询（Generic Inquiry）的用户才能连接。服务器在登录时通过 OData 检查 GI 的可读性（而非角色成员身份）；无访问权限的用户会看到访问被拒绝页面。您可以任意限制该 GI——推荐使用标记为 MCP Access 的角色。GI 名称可通过 ACUMATICA_CANARY_GI 配置。

• 同意确认页。 通过访问检查后，用户必须确认其数据将由外部 AI 模型处理，之后 MCP 会话才会激活。

• 敏感字段脱敏。 工具响应会自动扫描敏感字段名称（SSN、银行账户、工资、信用卡等），匹配的值会被替换为 [REDACTED]。模式可通过 REDACT_PATTERNS 和 REDACT_SKIP 环境变量配置。

• 基于角色的访问。 用户的 Acumatica 角色决定了他们可以读取哪些记录。如果用户在 Acumatica 中没有某条记录的访问权限，那么通过 MCP 服务器也无法访问。

• 只读。 当前所有工具均为只读查询。不会创建、修改或删除任何数据。

• 速率限制。 默认情况下，每个用户 3 个并发请求、每分钟 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 解耦，支持在 Node.js 上使用 Redis、SQLite 或其他存储后端进行自托管部署。详见自托管指南。

技术栈

• 运行时： 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 — 版权所有 2026 Hall Boys, Inc.