@casys/mcp-erpnext

MCP server for ERPNext / Frappe ERP — 123 tools across 14 categories, with 7 interactive UI viewers.

Connect any MCP-compatible AI agent (Claude Desktop, Claude Code, VS Code Copilot, custom) to your ERPNext instance via the Model Context Protocol.

Works with self-hosted and ERPNext Cloud (frappe.cloud) instances.

Built on @casys/mcp-server — the MCP server framework (concurrency, auth, MCP Apps, observability) that powers this project.

Screenshots

Interactive viewers rendered inside an MCP host, driven entirely by tool results.

What's New

See the CHANGELOG for the full release history, or the latest release for the current version's highlights.

Quick Start

Prerequisites

Generate API credentials in ERPNext:

1. Login to ERPNext → top-right menu → My Settings
2. Section API Access → Generate Keys
3. Copy API Key and API Secret

Claude Desktop / Claude Code (npm)

{
  "mcpServers": {
    "erpnext": {
      "command": "npx",
      "args": ["-y", "@casys/mcp-erpnext"],
      "env": {
        "ERPNEXT_URL": "http://localhost:8000",
        "ERPNEXT_API_KEY": "your-api-key",
        "ERPNEXT_API_SECRET": "your-api-secret"
      }
    }
  }
}

Works with ERPNext Cloud — set ERPNEXT_URL to your Frappe Cloud URL (e.g. https://mycompany.erpnext.com or https://mysite.frappe.cloud). API key authentication works the same way on self-hosted and cloud instances.

VS Code Copilot

Add to .vscode/mcp.json:

{
  "servers": {
    "erpnext": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@casys/mcp-erpnext"],
      "env": {
        "ERPNEXT_URL": "http://localhost:8000",
        "ERPNEXT_API_KEY": "your-api-key",
        "ERPNEXT_API_SECRET": "your-api-secret"
      }
    }
  }
}

Deno (stdio)

{
  "mcpServers": {
    "erpnext": {
      "command": "deno",
      "args": ["run", "--allow-all", "server.ts"],
      "env": {
        "ERPNEXT_URL": "http://localhost:8000",
        "ERPNEXT_API_KEY": "your-api-key",
        "ERPNEXT_API_SECRET": "your-api-secret"
      }
    }
  }
}

HTTP mode

ERPNEXT_URL=http://localhost:8000 \
ERPNEXT_API_KEY=xxx \
ERPNEXT_API_SECRET=xxx \
npx -y @casys/mcp-erpnext --http --port=3012

Note: HTTP mode binds to 127.0.0.1 (loopback) by default as of v2.4.2. For Docker or multi-host setups, add --hostname=0.0.0.0.

Deno (HTTP mode)

ERPNEXT_URL=http://localhost:8000 \
ERPNEXT_API_KEY=xxx \
ERPNEXT_API_SECRET=xxx \
deno run -A npm:@casys/mcp-erpnext --http --port=3012

Note: Versions ≤ 2.3.1 of the npm bundle crashed with ReferenceError: Deno is not defined in HTTP mode — fixed in 2.4.0 (@casys/mcp-server ≥ 0.21.1). If you hit this error, upgrade with npx -y @casys/mcp-erpnext@latest, or use the Deno runner above. See docs/known-issues.md.

Category filtering

Load only the categories you need:

npx -y @casys/mcp-erpnext --categories=sales,inventory

Fresh Instance Setup

On a fresh ERPNext instance (no setup wizard), you need to create master data before using business tools. Use erpnext_doc_create for prerequisites:

1. Warehouse Types: Transit, Default
2. UOMs: Nos, Kg, Unit, Set, Meter
3. Item Groups: All Item Groups (is_group=1), then Products, Raw Material (parent=All Item Groups)
4. Territories: All Territories (is_group=1), then France, etc.
5. Customer Groups: All Customer Groups (is_group=1), then Commercial, etc.
6. Supplier Groups: All Supplier Groups (is_group=1), then Hardware, etc.
7. Company: requires Warehouse Types to exist first

UI Viewers

Seven interactive MCP Apps viewers, registered as ui://mcp-erpnext/{name}:

Cross-viewer navigation

Viewers communicate via app.sendMessage() — clicking a button in one viewer injects a message into the conversation, which triggers the AI to call the right tool and open the appropriate viewer.

The server auto-injects navigation metadata into tool results:

• _rowAction — which tool to call when a row is clicked
• _sendMessageHints — navigation buttons shown in detail panels (e.g. "Orders", "Invoices")
• _drillDown / _trendDrillDown — sendMessage templates for KPI and chart click-through

Refresh model

All viewers carry a refreshRequest payload for safe revalidation via app.callServerTool():

• kanban-viewer revalidates after mutations and on focus
• All other viewers support focus refresh + manual refresh button

Building UI viewers

cd src/ui
npm install
node build-all.mjs

Tools (123)

123 tools across 14 categories. Each _list tool returns interactive results via the doclist-viewer with row click, inline detail, and cross-viewer navigation.

• Sales (17) — Customers, Sales Orders, Invoices, and Quotations with full CRUD, Submit, and Cancel.
• Purchasing (11) — Suppliers, Purchase Orders, Purchase Invoices, Receipts, and Supplier Quotations.
• Inventory (9) — Items, Stock Balance, Warehouses, and Stock Entries.
• Accounting (6) — Chart of Accounts, Journal Entries, and Payment Entries.
• HR (12) — Employees, Attendance, Leave Applications, Salary Slips, Payroll Entries, and Expense Claims.
• Project (9) — Projects, Tasks (with native assignment), and Timesheets.
• Delivery (5) — Delivery Notes and Shipments.
• Manufacturing (7) — BOMs, Work Orders, and Job Cards.
• CRM (8) — Leads, Opportunities, Contacts, and Campaigns.
• Assets (8) — Assets, Movements, Maintenance records, and Categories.
• Operations (9) — Generic CRUD and native assignment for any DocType (erpnext_doc_*).
• Kanban (2) — Read-write boards for Task, Opportunity, and Issue with drag-and-drop.
• Analytics (17) — 11 analytics charts (bar, area, treemap, radar, scatter, P&L…), 5 KPIs with sparklines, and a sales funnel.
• Setup (3) — Company creation and assignable user listing.

Full per-tool reference with parameters: docs/tools.md.

Environment Variables

Architecture

server.ts           # MCP server (stdio + HTTP + inspector)
mod.ts              # Public API
deno.json           # Package config
src/
  api/
    frappe-client.ts  # Frappe REST HTTP client (zero-dependency)
    types.ts          # Frappe type definitions
  kanban/
    adapters/         # Per-DocType kanban adapters (task, opportunity, issue)
    definitions.ts    # Board registry
    types.ts          # Shared kanban contracts
  tools/
    sales.ts          # 17 sales tools
    inventory.ts      # 9 inventory tools
    purchasing.ts     # 11 purchasing tools
    accounting.ts     # 6 accounting tools
    hr.ts             # 12 HR tools
    project.ts        # 9 project tools
    delivery.ts       # 5 delivery tools
    manufacturing.ts  # 7 manufacturing tools
    crm.ts            # 8 CRM tools
    assets.ts         # 8 asset tools
    operations.ts     # 9 generic CRUD tools
    setup.ts          # 3 company/setup tools
    kanban.ts         # 2 read-write kanban tools
    analytics.ts      # 17 analytics tools (charts, KPIs, funnel)
    ui-refresh.ts     # Auto-inject _rowAction, _sendMessageHints, _drillDown
    mod.ts            # Tool registry
    types.ts          # Tool interface
  client.ts           # ErpNextToolsClient
  runtime.ts          # Deno runtime adapter
  runtime.node.ts     # Node.js runtime adapter
  *_test.ts           # Tests are colocated with source files
  ui/
    shared/           # ActionButton, InfoField, theme, branding, refresh
    doclist-viewer/   # Generic document list (inline detail, chip filters)
    invoice-viewer/   # Invoice display (item drill-down, actions)
    stock-viewer/     # Stock balance (detail panel, sendMessage)
    chart-viewer/     # Universal chart renderer (12 types, click drill-down)
    kanban-viewer/    # Read-write kanban (drag, edit, sendMessage)
    kpi-viewer/       # KPI card (clickable number + sparkline)
    funnel-viewer/    # Sales funnel (trapezoid stages, click-through)
    viewers.ts        # Viewer registry
docs/
  ROADMAP.md          # Feature roadmap
  coverage.md         # Test coverage matrix

npm Package

The npm package (@casys/mcp-erpnext) is a single self-contained bundle with zero runtime dependencies. UI viewers are embedded. Requires Node >= 20.

Development

# Run tests
deno test --allow-all src/

# Type check
deno task check

# Start HTTP server (dev)
deno task serve

# Launch MCP Inspector
deno task inspect

# Build UI viewers
deno task ui:build

# Full local release preflight (no publish)
deno task release:check

# Dev a specific viewer with HMR
cd src/ui && npm run dev:kanban

Contributing

Contributions are welcome — see CONTRIBUTING.md to get started, and AGENTS.md for the full architecture and conventions.

Release Flow

Releases are manual and explicit:

1. Update deno.json, server.ts, and CHANGELOG.md.
2. Run deno task release:check locally.
3. Commit and push the release commit to main.
4. Create the GitHub release/tag, for example v2.3.0.
5. Run the Publish workflow manually to publish the same version to JSR and npm.

The package name stays @casys/mcp-erpnext; releases only bump the package version.

License

MIT