acu-mcp (archived — migrated to tuxton-platform)

This TypeScript project has been ported to Python and moved into the tuxton-platform monorepo as apps/acu_mcp/.

New home: /home/huyson/develop/tuxton-platform/apps/acu_mcp/

The port reuses the shared packages/tuxton_acumatica/ client (OAuth2 + entity REST + OData v3) so acu_etl and acu_mcp can evolve together. OData v4 tools were dropped from the initial port because the /ODataV4/ route is currently 406ing at the IIS layer regardless of client — the underlying helpers still exist in tuxton_acumatica and can be re-wired as tools when the server-side issue clears.

This directory is kept in place for historical reference but should not receive new work. Any new Acumatica REST integration goes into apps/acu_mcp/ or packages/tuxton_acumatica/.

---

An MCP (Model Context Protocol) server that connects Claude to Acumatica ERP for read-only analytics queries.

Tools

Tool	Description
query_sales_orders	List and filter sales orders with OData expressions
get_sales_order	Get a single order with full line item detail
list_inventory_items	List stock items filtered by class, status, etc.
get_inventory_item	Get a specific item with warehouse stock quantities
query_shipments	List and filter shipments
get_shipment	Get a single shipment with line detail
query_invoices	List and filter AR invoices
get_invoice	Get a single invoice with line detail
query_purchase_orders	List and filter purchase orders
get_purchase_order	Get a single purchase order with line detail
query_customers	List and filter customers
get_customer	Get a single customer with contacts and addresses
list_odata_entities	Discover all available Generic Inquiry entity sets via OData
query_odata	Query any Generic Inquiry by name with OData filter, select, orderby, top, skip

Prerequisites

• Node.js 18.3 or later
• An Acumatica instance with a dedicated service account (see Acumatica Setup below)

Installation

git clone git@github.com:lycheejello/acu-mcp.git
cd acu-mcp
npm install
npm run build

Configuration

Copy the example env file and fill in your values:

cp .env.example .env

ACU_BASE_URL=https://yourinstance.acumatica.com/YourTenant
# OData URL is derived automatically: {ACU_BASE_URL}/odata/{ACU_COMPANY}
ACU_USERNAME=mcp-user
ACU_PASSWORD=your_password
ACU_COMPANY=YourCompanyLoginName
ACU_ENDPOINT=Default
ACU_VERSION=25.200.001
# Required for OData access (see Acumatica Setup below)
ACU_CLIENT_ID=your_client_id@YourCompanyLoginName
ACU_CLIENT_SECRET=your_client_secret

Warning: Use a dedicated service account (e.g. mcp-user). Do NOT use your personal Acumatica login.

Claude Integration

Claude Code (CLI)

Run once to register the server globally:

claude mcp add --scope user acumatica \
  -e ACU_BASE_URL=https://yourinstance.acumatica.com/YourTenant \
  -e ACU_USERNAME=mcp-user \
  -e ACU_PASSWORD=your_password \
  -e ACU_COMPANY=YourCompanyLoginName \
  -e ACU_ENDPOINT=Default \
  -e ACU_VERSION=25.200.001 \
  -e ACU_CLIENT_ID=your_client_id@YourCompanyLoginName \
  -e ACU_CLIENT_SECRET=your_client_secret \
  -- node /absolute/path/to/acu-mcp/dist/index.js

Restart Claude Code after running this command.

Claude Desktop — macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "acumatica": {
      "command": "node",
      "args": ["/absolute/path/to/acu-mcp/dist/index.js"],
      "env": {
        "ACU_BASE_URL": "https://yourinstance.acumatica.com/YourTenant",
        "ACU_USERNAME": "mcp-user",
        "ACU_PASSWORD": "your_password",
        "ACU_COMPANY": "YourCompanyLoginName",
        "ACU_ENDPOINT": "Default",
        "ACU_VERSION": "25.200.001",
        "ACU_CLIENT_ID": "your_client_id@YourCompanyLoginName",
        "ACU_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Claude Desktop — Windows

Edit %APPDATA%\Claude\claude_desktop_config.json with the same structure, using a Windows path:

"args": ["C:\\absolute\\path\\to\\acu-mcp\\dist\\index.js"]

Restart Claude Desktop after saving.

Verify

After restarting, ask Claude:

"Show me the last 5 open sales orders"

Claude should call query_sales_orders and return live data.

Acumatica Setup

Connected Applications (required for OData)

OData access requires a Connected Application registered in Acumatica. Create one per integration (e.g. one for this MCP server, one for Azure Functions) so credentials can be managed and revoked independently.

In SM301000 (Connected Applications):

1. Click + to add a new application
2. Set Client Name (display name only, e.g. TuxtonTools MCP or TuxtonTools ETL)
3. Leave Client ID blank to let Acumatica generate one, or set a custom value
4. Set Flow to Resource Owner Password — this is the grant type used by the code
5. Save
6. On the Shared Secrets tab, click +, enter a Description (e.g. acu-mcp-prod), and click Generate Secret — copy the secret password immediately, it will not be shown again
7. Note the Client ID and the generated Shared Secret password — use these as ACU_CLIENT_ID and ACU_CLIENT_SECRET

Note: Create separate Connected Applications for each integration. This allows independent credential rotation and audit trails.

Service Account

In SM201010 (Users), create a dedicated service account:

1. Set Login Name (e.g. mcp-user) and a strong password
2. Enable the Web Service Access checkbox
3. On the Roles tab, assign read-only viewer roles for each module (Sales Orders, Inventory, AR, AP, etc.)
4. Set Max Number of API Logins to at least 5 to allow concurrent sessions during development

Development

npm run dev    # run with tsx (no build step)
npm run build  # compile TypeScript → dist/
npm start      # run compiled output

Adding a New Entity

1. Create src/tools/{entity}.ts and export a register{Entity}Tools(server: McpServer) function
2. Call it from src/tools/index.ts
3. No other changes needed

Roadmap

See PLAN.md for the full architecture and phased development plan.

Phase 1 (complete): Core server with 12 REST tools across Sales Orders, Inventory, Shipments, Invoices, Purchase Orders, and Customers. Phase 2 (in progress): OData/GI passthrough done (list_odata_entities + query_odata); GL balance tools and MCP Resources/Prompts still pending. Phase 3: OAuth 2.0, HTTP/SSE transport, production hardening.