@casys/mcp-erpnext

MCP server for ERPNext / Frappe ERP — 120 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.

Screenshots

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

doclist-viewer — any DocType as a sortable table with chip filters and an inline detail panel	invoice-viewer — invoice with parties, line items, item drill-down and Submit/Cancel/Payments
funnel-viewer — Lead → Opportunity → Quotation → Order with conversion rates	kpi-viewer — big-number KPI with delta vs last period and a sparkline
chart-viewer — universal Recharts renderer (here: stock levels)	stock-viewer — stock balance with color-coded quantity badges
kanban-viewer — read-write board (Task / Opportunity / Issue) with inline edit	chart-viewer — composed dual-axis chart (here: profit & loss)

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.

Zero dependencies — single self-contained bundle. Requires Node >= 20.

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

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. This creates a seamless drill-down
experience without leaving the chat.

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 (120)

14 categories covering the full ERPNext surface. Each _list tool returns
interactive results in the doclist-viewer with row click, inline detail, and
cross-viewer navigation.

Full tool reference with all 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     # 7 generic CRUD tools
    setup.ts          # 2 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.

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

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