convez.ai
MCP ServerIntegração & APIsAvançado
hallboys

MCP4Acumatica

hallboys/MCP4Acumatica

Integração Claude ↔ Acumatica ERP com OAuth, RBAC e redação de PII

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que conecta Claude ao Acumatica ERP 2025 R2, rodando em Cloudflare Workers com autenticação OAuth por usuário. Oferece 48 ferramentas de integração com controle de acesso baseado em papéis, redação automática de campos sensíveis e auditoria estruturada.

Instalação

$npx convez-ai hallboys/MCP4Acumatica

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
21
Forks
18
Acompanhando
5
Saúde
62%
Último commit
há 2 semanas
Versão
25R2-0.56.1
Issues abertas
0
Contribuidores
3

Casos de uso

  • Consultas de dados financeiros e operacionais do Acumatica via Claude
  • Automação de fluxos de trabalho ERP com IA usando dados em tempo real
  • Acesso seguro a registros do ERP respeitando papéis de usuário Acumatica

Veredito

Integração técnica robusta e bem pensada para Acumatica com camadas fortes de segurança (OAuth, RBAC, redação de PII) e auditoria. Exige infraestrutura Cloudflare e configuração prévia no ERP, direcionado a empresas que usam Acumatica em produção.

README

A tradução para o português deste README ainda está na fila.

MCP4Acumatica

Disclaimer: This project is an independent, community-built integration and is not affiliated with, endorsed by, or supported by Acumatica, Inc. "Acumatica" is a registered trademark of Acumatica, Inc. Use of the Acumatica name and API is for interoperability purposes only.

A remote Model Context Protocol (MCP) server that connects Claude to Acumatica ERP 2025 R2. Runs on Cloudflare Workers with per-user OAuth authentication against your Acumatica instance.

Each user authenticates with their own Acumatica credentials. Their Acumatica role controls which records they can access. The MCP server additionally requires a specific Acumatica role for access, shows a consent interstitial, and automatically redacts sensitive fields before data reaches the AI model.

Features

  • 48 tools -- 38 read-only lookups + 6 utility/discovery + 4 schema-knowledge tools (see Available Tools)
  • Per-user OAuth -- users log in with their Acumatica credentials (or SSO)
  • Role-based access -- Acumatica's security model governs what each user sees
  • Role gate -- only users with a designated Acumatica role (e.g., MCP Access) can connect
  • Consent interstitial -- users must acknowledge AI data processing before accessing tools
  • Sensitive field redaction -- SSN, bank accounts, salary, and other PII fields are automatically redacted before data leaves the server
  • Rate limiting -- 3 concurrent requests, 40 requests/minute per user
  • Pagination refusal -- list/query tools return a structured { truncated, paginationSupported: false, actionRequired } envelope when results hit the record cap, instructing the AI to ask the user for a narrower filter rather than calling the tool again
  • Structured audit logging -- all tool invocations, auth events, and field redactions are logged
  • Admin console -- web-based admin interface at /docs/admin for viewing logs and managing runtime settings without redeploying
  • Long-term log retention -- R2-backed log storage via Cloudflare Logpush with searchable log viewer

Architecture

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

Prerequisites

  • Node.js >= 18
  • A Cloudflare account (Workers paid plan for Durable Objects)
  • An Acumatica 2025 R2 instance with:
    • A Connected Application configured in SM303010
    • OAuth 2.0 enabled with api openid profile email offline_access scopes (offline_access is required for refresh tokens)
    • A redirect URI pointing to your worker's /callback endpoint
    • An MCP Access role (SM201005) -- a marker role with no permissions required
    • An MCPAccess Generic Inquiry (SM208000) -- a trivial GI assigned only to the MCP Access role, with Expose via OData enabled (see Architecture docs for details)

Setup

There are three install paths. All three rely on the same Acumatica-side prerequisites — finish those first (see "Acumatica-side configuration" below) regardless of which path you pick.

PathBest forTerminal needed?
A. Deploy to Cloudflare buttonAdopters who want a fully GUI installNo
B. One-line installerDevelopers who already have git / node / npmYes (one command)
C. Manual setupAnyone who wants to inspect each stepYes

Path A — Deploy to Cloudflare button (no terminal)

Deploy to Cloudflare

The button forks this repo to your GitHub account, reads wrangler.jsonc, auto-creates the KV namespace and R2 bucket, prompts for secrets, and deploys. Step-by-step:

  1. Click the button. Cloudflare will ask you to sign in (or create an account) and authorize a GitHub fork.
  2. Confirm bindings. The KV namespace (TOKEN_STORE / OAUTH_KV) and R2 bucket (mcp4acumatica-logs) are created automatically.
  3. Set secrets. When prompted, paste:
    • ACUMATICA_CLIENT_ID — from your Connected Application (SM303010)
    • ACUMATICA_CLIENT_SECRET — from the same screen
    • COOKIE_ENCRYPTION_KEY — open your browser console on any page and run:
      [...crypto.getRandomValues(new Uint8Array(32))].map(b => b.toString(16).padStart(2,'0')).join('')
      
      Copy the resulting 64-character hex string.
    • ADMIN_SECRET — any password you'll remember (protects the /docs/admin console). Generate one with [...crypto.getRandomValues(new Uint8Array(24))].map(b => b.toString(16).padStart(2,'0')).join('') if you don't have a preference.
  4. Deploy. Cloudflare connects the fork to Workers Builds and pushes the first deployment.
  5. Update the Acumatica vars. After the deploy completes, open Workers & Pages → mcp4acumatica → Settings → Variables and Secrets in the Cloudflare dashboard and edit:
    • ACUMATICA_URL (e.g. https://yourcompany.acumatica.com)
    • ACUMATICA_TENANT (your login company)
    • Optionally ACUMATICA_MAX_RECORDS, ACUMATICA_MCP_ROLE, REDACT_PATTERNS, REDACT_SKIP Click Save and Deploy — Cloudflare redeploys with the new values.
  6. Add a redirect URI to your Connected Application. Your worker is now reachable at https://mcp4acumatica.<your-account>.workers.dev. Add https://<that-host>/callback to the redirect URIs in Acumatica's SM303010 screen. (To use a custom domain instead, see "Custom domain" below.)
  7. Test the deploy. Visit https://<your-host>/docs/admin/preflight, log in with your ADMIN_SECRET, and run the preflight diagnostic. It probes Acumatica connectivity, the OIDC discovery endpoint, the Connected App credentials, the tenant path, and the contract API version — any misconfiguration is called out by name.

After this point Claude can connect (see "Connecting Claude" below).

Path B — One-line installer (terminal)

If you already have git, node, and npm, run:

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

This clones the repo, installs dependencies, and runs ./setup.sh. The setup script prompts for the Acumatica values you must supply (URL, tenant, Connected App client ID and secret), auto-generates the crypto secrets, creates the KV namespace and R2 bucket, uploads secrets, deploys, and then runs the preflight check.

If you prefer to inspect the script first:

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

Path C — Manual setup (terminal)

1. Clone and install

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

2. Create KV namespace

npx wrangler kv namespace create TOKEN_STORE

Note the namespace ID from the output — you'll paste it into wrangler.jsonc next. The same ID is used for both the TOKEN_STORE and OAUTH_KV bindings.

3. Configure wrangler

wrangler.jsonc is tracked in the repo as the deploy template. Edit it in place and fill in:

  • The KV namespace ID from step 2 (both TOKEN_STORE and OAUTH_KV bindings — same id)
  • ACUMATICA_URL — your Acumatica instance URL (e.g. https://yourcompany.acumatica.com)
  • ACUMATICA_TENANT — your Acumatica company/tenant name

To keep your local values out of git status (so you can still pull updates without conflicts):

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

4. Set secrets

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. Deploy

npx wrangler deploy

6. Local development (optional)

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

Acumatica-side configuration

These steps are required regardless of which install path you pick. They can't be automated — Acumatica's API doesn't expose them.

Connected Application (SM303010)

  1. In Acumatica: System > Integration > Connected Applications (SM303010).
  2. Create a new Connected Application.
  3. Set the OAuth 2.0 Flow to Authorization Code.
  4. Add a redirect URI: https://<your-worker-url>/callback (use the *.workers.dev hostname or your custom domain).
  5. Set the scope to api openid profile email offline_access (offline_access is required so Acumatica issues refresh tokens).
  6. Note the Client ID and Client Secret — you'll provide these as secrets during deploy.

Role and Generic Inquiry (SM201005, SM208000)

The MCP server requires users to have a specific Acumatica role before they can access AI tools. This is enforced via a canary Generic Inquiry (GI) that is assigned only to that role.

  1. Create role: System > Access Rights > User Roles (SM201005) → create a role named MCP Access. No screen permissions are needed — it's purely a marker role.
  2. Create Generic Inquiry: System > Customization > Generic Inquiry (SM208000) → create a GI named MCPAccess with any trivial query (a single column from any table is fine). Assign it only to the MCP Access role. Enable Expose via OData.
  3. Assign role to users: Assign the MCP Access role to each Acumatica user who should have AI assistant access.

The role name is configurable via the ACUMATICA_MCP_ROLE variable. Edit it in the Cloudflare dashboard (Variables and Secrets) or in wrangler.jsonc.

Custom domain (optional)

The deploy gives you a *.workers.dev hostname out of the box. To attach a branded hostname:

  • Via the Cloudflare dashboard: Workers & Pages → mcp4acumatica → Settings → Domains & Routes → Add. The domain's zone must be on your Cloudflare account.
  • Via wrangler.jsonc: uncomment the routes block at the top of the file, edit pattern and zone_name, redeploy.

If you change hostnames, remember to add the new https://<host>/callback to your Connected Application's redirect URIs in SM303010.

Connecting Claude

Claude.ai / Claude Desktop

  1. Go to Settings > Connectors
  2. Click Add Connector and enter the URL: https://<your-worker-url>/mcp
  3. On first use, you'll be redirected to your Acumatica login page
  4. If your account has the MCP Access role, you'll see a consent page explaining AI data processing
  5. After acknowledging consent, Claude will have access to all 48 tools

Claude Code (CLI)

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

API (via Anthropic SDK)

When using the Anthropic API with MCP, point the MCP client to https://<your-worker-url>/mcp. The server supports OAuth 2.1 with Dynamic Client Registration at /register.

Available Tools

Core

ToolDescription
acumatica_get_customerCustomer record with contacts, credit rules, balance
acumatica_get_vendorVendor record with contacts, terms, tax info
acumatica_get_sales_orderSales order with line items, totals, shipping

Financial / Accounting

ToolDescription
acumatica_get_invoiceAR invoice with line items and tax details
acumatica_get_billAP bill with line items and PO linkage
acumatica_get_journal_transactionGL journal batch with debit/credit details
acumatica_get_paymentAR payment with applied documents and orders
acumatica_get_accountGL chart of accounts lookup
acumatica_get_checkAP check/vendor payment with history

Inventory & Warehouse

ToolDescription
acumatica_get_stock_itemStock item with pricing, warehouse qty, vendors
acumatica_get_non_stock_itemNon-stock item (service, labor, expense)
acumatica_get_inventory_quantity_availableReal-time available quantity across warehouses
acumatica_get_inventory_summaryAggregated inventory balances by warehouse
acumatica_get_warehouseWarehouse with locations and settings
acumatica_get_item_classItem classification defaults

Purchasing

ToolDescription
acumatica_get_purchase_orderPO with line items, vendor, totals
acumatica_get_purchase_receiptReceipt with received qty and PO linkage

Projects

ToolDescription
acumatica_get_projectProject header, status, financials
acumatica_get_project_taskTask within a project
acumatica_get_project_budgetBudget line with actuals vs budgeted
acumatica_get_project_transactionProject cost/revenue transaction details

Service & Field

ToolDescription
acumatica_get_caseSupport case with SLA, priority, time tracking
acumatica_get_service_orderField service order with details and appointments
acumatica_get_appointmentScheduled/actual times, staff, cost/profit

Sales & CRM

ToolDescription
acumatica_get_contactCRM contact with address, phone, owner
acumatica_get_business_accountUnified prospect/customer/vendor record
acumatica_get_opportunitySales pipeline deal with products and amounts
acumatica_get_leadMarketing lead with status and source
acumatica_get_salespersonSales rep with commission settings

Shipping & Fulfillment

ToolDescription
acumatica_get_shipmentShipment with packages, tracking, freight
acumatica_get_sales_invoiceInvoice with SO/shipment linkage

HR & Payroll

ToolDescription
acumatica_get_employeeEmployee with contact and financial settings
acumatica_get_expense_claimExpense report with line items and approval
acumatica_get_time_entryTime tracking with project, billable/overtime

CRM Activities

ToolDescription
acumatica_get_emailEmail activity with from/to/body
acumatica_get_eventCalendar event with attendees
acumatica_get_activityGeneral CRM activity
acumatica_get_taskCRM task with related activities

Utility / Discovery

ToolDescription
acumatica_run_inquiryExecute any configured Generic Inquiry (GI) with filtering
acumatica_list_entitiesList/search any entity with OData filtering, sorting, field selection
acumatica_describe_entityDiscover fields, types, and sub-entities for any entity
acumatica_list_generic_inquiriesList available GIs exposed via OData
acumatica_describe_inquiryInfer field schema for a GI before running it
acumatica_clear_cacheClear cached metadata when schemas change

Tip: Use acumatica_describe_entity first to discover available fields, then acumatica_list_entities to search/filter. For Generic Inquiries, use acumatica_list_generic_inquiries to find GI names and acumatica_describe_inquiry to see available fields. See docs/example-prompts.md for usage patterns.

Documentation

Detailed documentation is available in the docs/ folder:

  • Tool Reference -- Complete specification for all 48 tools with parameters and endpoints
  • Example Prompts -- Example prompts for Claude and other MCP clients organized by use case
  • OData Filtering Guide -- Guide to $filter, $orderby, $select, $expand, and $top query parameters
  • Schema Knowledge -- Offline schema-discovery tools for building integrations/customizations, and how the schema index is built
  • Architecture -- Detailed architecture, OAuth flow, security model, and design decisions
  • Self-Hosting Guide -- How to run the MCP server on Node.js or other platforms outside Cloudflare
  • Upgrading Acumatica -- Steps to take when changing or upgrading the connected Acumatica version

Security

  • No stored credentials. The MCP server does not store Acumatica passwords. It uses OAuth 2.0 authorization code flow -- users authenticate directly with Acumatica.
  • Per-user tokens. Each user's Acumatica access token is stored in the platform key-value store (Cloudflare KV on the default deployment), scoped to their username. Tokens are automatically refreshed when expired. If a refresh token expires, the connection re-authenticates automatically instead of requiring a manual reconnect.
  • Role gate. Only users with the MCP Access role (configurable) can connect. This is enforced via a canary Generic Inquiry check during login -- users without the role see an access denied page.
  • Consent interstitial. After passing the role check, users must acknowledge that their data will be processed by an external AI model before the MCP session activates.
  • Sensitive field redaction. Tool responses are automatically scanned for sensitive field names (SSN, bank accounts, salary, credit card, etc.) and matched values are replaced with [REDACTED]. Patterns are configurable via REDACT_PATTERNS and REDACT_SKIP environment variables.
  • Role-based access. The user's Acumatica role determines which records they can read. If a user doesn't have access to a record in Acumatica, they won't be able to access it through the MCP server either.
  • Read-only. All current tools are read-only lookups. No data is created, modified, or deleted.
  • Rate limiting. 3 concurrent requests, 40 requests per minute, and a configurable record cap per query to protect your Acumatica instance.
  • Pagination refusal. The list/query tools (acumatica_list_entities, acumatica_run_inquiry, acumatica_list_generic_inquiries) do not support pagination. When a response hits ACUMATICA_MAX_RECORDS, the tool returns a structured envelope (truncated: true, paginationSupported: false, actionRequired: "...") instructing the AI to stop and ask the user for a narrower filter rather than retrieving more records.
  • Audit logging. All tool invocations, auth events (login success/denied, consent accepted), and field redaction events are logged as structured JSON. View with npx wrangler tail.

Platform Portability

While the default deployment targets Cloudflare Workers, the tool handlers and core libraries are platform-agnostic. A storage abstraction (IKeyValueStore interface + AppEnv type) decouples tool logic from Cloudflare-specific APIs, enabling self-hosted deployments on Node.js with Redis, SQLite, or other storage backends. See the Self-Hosting Guide for details.

Tech Stack

Development

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

License

Apache 2.0 -- Copyright 2026 Hall Boys, Inc.

Ver o original no GitHub

Bom para

Relacionados