Skip to content
Back to search

mcp-erpnext

Let AI agents operate your ERPNext — documents, workflows, and interactive viewers

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/casys-ai--mcp-erpnext/badge.svg)](/listings/casys-ai--mcp-erpnext)

HTML

<a href="/listings/casys-ai--mcp-erpnext"><img src="/api/listings/casys-ai--mcp-erpnext/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

For a shared, always-on server rather than one process per client: [how to run the HTTP server](docs/http-deployment.md). Note it is breaking for pre-2026 HTTP clients in 3.0.0.

Category filtering

Load only the categories you need:

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 391 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. English | [繁體中文](README.zh-TW.md)
  2. # @casys/mcp-erpnext
  3. [![JSR](https://jsr.io/badges/@casys/mcp-erpnext)](https://jsr.io/@casys/mcp-erpnext)
  4. [![npm](https://img.shields.io/npm/v/@casys/mcp-erpnext?logo=npm&color=cb3837)](https://www.npmjs.com/package/@casys/mcp-erpnext)
  5. [![CI](https://github.com/Casys-AI/mcp-erpnext/actions/workflows/test.yml/badge.svg)](https://github.com/Casys-AI/mcp-erpnext/actions/workflows/test.yml)
  6. [![MCP](https://img.shields.io/badge/MCP-server-1f6feb?logo=modelcontextprotocol&logoColor=white)](https://modelcontextprotocol.io)
  7. [![M8ven Score](https://m8ven.ai/badge/mcp/casys-ai-mcp-erpnext-1kev4k)](https://m8ven.ai/mcp/casys-ai-mcp-erpnext-1kev4k)
  8. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  9. Let any MCP-compatible AI agent operate your [ERPNext](https://erpnext.com) /
  10. Frappe instance — documents, workflows, and interactive viewers inside the host
  11. (Claude Desktop, Claude Code, VS Code Copilot, or custom).
  12. Works with **self-hosted** and **ERPNext Cloud** (frappe.cloud) instances.
  13. > Built on **[@mcpview/server](https://github.com/mcpview/mcpview)** — the MCP
  14. > server framework (concurrency, auth, MCP Apps, observability) that powers this
  15. > project. See [mcpview.dev](https://mcpview.dev).
  16. ## Screenshots
  17. Interactive viewers rendered inside an MCP host, driven entirely by tool
  18. results.
  19. <table>
  20. <tr>
  21. <td width="50%" align="center">
  22. <img src="docs/assets/doclist-viewer.png" alt="Document list viewer with chip filters and inline detail" width="100%"><br>
  23. <sub><b>doclist-viewer</b> — any DocType as a sortable table with chip filters and an inline detail panel</sub>
  24. </td>
  25. <td width="50%" align="center">
  26. <img src="docs/assets/invoice-viewer.png" alt="Invoice viewer with line items and actions" width="100%"><br>
  27. <sub><b>invoice-viewer</b> — invoice with parties, line items, item drill-down and Submit/Cancel/Payments</sub>
  28. </td>
  29. </tr>
  30. <tr>
  31. <td width="50%" align="center">
  32. <img src="docs/assets/funnel-viewer.png" alt="Sales funnel viewer" width="100%"><br>
  33. <sub><b>funnel-viewer</b> — Lead → Opportunity → Quotation → Order with conversion rates</sub>
  34. </td>
  35. <td width="50%" align="center">
  36. <img src="docs/assets/kpi-viewer.png" alt="KPI viewer with sparkline" width="100%"><br>
  37. <sub><b>kpi-viewer</b> — big-number KPI with delta vs last period and a sparkline</sub>
  38. </td>
  39. </tr>
  40. <tr>
  41. <td width="50%" align="center">
  42. <img src="docs/assets/chart-viewer.png" alt="Chart viewer" width="100%"><br>
  43. <sub><b>chart-viewer</b> — universal Recharts renderer (here: stock levels)</sub>
  44. </td>
  45. <td width="50%" align="center">
  46. <img src="docs/assets/stock-viewer.png" alt="Stock balance viewer" width="100%"><br>
  47. <sub><b>stock-viewer</b> — stock balance with color-coded quantity badges</sub>
  48. </td>
  49. </tr>
  50. <tr>
  51. <td width="50%" align="center">
  52. <img src="docs/assets/kanban-viewer.png" alt="Read-write kanban board" width="100%"><br>
  53. <sub><b>kanban-viewer</b> — read-write board (Task / Opportunity / Issue) with inline edit</sub>
  54. </td>
  55. <td width="50%" align="center">
  56. <img src="docs/assets/profit-loss.png" alt="Profit and loss composed chart" width="100%"><br>
  57. <sub><b>chart-viewer</b> — composed dual-axis chart (here: profit &amp; loss)</sub>
  58. </td>
  59. </tr>
  60. </table>
  61. ## Releases
  62. See the
  63. [latest release](https://github.com/Casys-AI/mcp-erpnext/releases/latest) for
  64. the current version's highlights and the [CHANGELOG](CHANGELOG.md) for the full
  65. release history.
  66. ## Documentation
  67. Organised by what you are doing, following [Diátaxis](https://diataxis.fr):
  68. | | |
  69. | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  70. | **Learning** — never used this before | [Your first tool call](docs/tutorial-first-tool-call.md) — from nothing to a working response in four steps |
  71. | **Doing** — you have a specific goal | [Seed a blank ERPNext instance](docs/fresh-instance-setup.md) · [Run the HTTP server](docs/http-deployment.md) · [Set up OAuth](docs/oauth-setup.md) · [Migrate from 3.0 to 3.1](docs/migration-3.0-to-3.1.md) · [Migrate to 2026-07-28](docs/migration-mcp-spec-2026-07-28.md) |
  72. | **Looking something up** | [Tools](docs/tools.md) · [Environment variables](docs/environment-variables.md) · [DocType coverage](docs/coverage.md) |
  73. | **Understanding why** | [Concepts](docs/concepts.md) — link resolution, transports, MRTR, and which cache does what · [ERPNext quirks](docs/erpnext-quirks.md) |
  74. ## Quick Start
  75. ### Prerequisites
  76. Generate API credentials in ERPNext:
  77. 1. Login to ERPNext → top-right menu → **My Settings**
  78. 2. Section **API Access** → **Generate Keys**
  79. 3. Copy `API Key` and `API Secret`
  80. ### Claude Desktop / Claude Code (npm)
  81. ```json
  82. {
  83. "mcpServers": {
  84. "erpnext": {
  85. "command": "npx",
  86. "args": ["-y", "@casys/mcp-erpnext"],
  87. "env": {
  88. "ERPNEXT_URL": "http://localhost:8000",
  89. "ERPNEXT_API_KEY": "your-api-key",
  90. "ERPNEXT_API_SECRET": "your-api-secret"
  91. }
  92. }
  93. }
  94. }
  95. ```
  96. > **Works with ERPNext Cloud** — set `ERPNEXT_URL` to your Frappe Cloud URL
  97. > (e.g. `https://mycompany.erpnext.com` or `https://mysite.frappe.cloud`). API
  98. > key authentication works the same way on self-hosted and cloud instances.
  99. ### VS Code Copilot
  100. Add to `.vscode/mcp.json`:
  101. ```json
  102. {
  103. "servers": {
  104. "erpnext": {
  105. "type": "stdio",
  106. "command": "npx",
  107. "args": ["-y", "@casys/mcp-erpnext"],
  108. "env": {
  109. "ERPNEXT_URL": "http://localhost:8000",
  110. "ERPNEXT_API_KEY": "your-api-key",
  111. "ERPNEXT_API_SECRET": "your-api-secret"
  112. }
  113. }
  114. }
  115. }
  116. ```
  117. ### Deno (stdio)
  118. ```json
  119. {
  120. "mcpServers": {
  121. "erpnext": {
  122. "command": "deno",
  123. "args": ["run", "--allow-all", "server.ts"],
  124. "env": {
  125. "ERPNEXT_URL": "http://localhost:8000",
  126. "ERPNEXT_API_KEY": "your-api-key",
  127. "ERPNEXT_API_SECRET": "your-api-secret"
  128. }
  129. }
  130. }
  131. }
  132. ```
  133. ### HTTP mode
  134. For a shared, always-on server rather than one process per client:
  135. [how to run the HTTP server](docs/http-deployment.md). Note it is breaking for
  136. pre-2026 HTTP clients in 3.0.0.
  137. ### Category filtering
  138. Load only the categories you need:
  139. ```bash
  140. npx -y @casys/mcp-erpnext --categories=sales,inventory
  141. ```
  142. Category and individual-tool exclusions are also supported, with
  143. environment-variable equivalents:
  144. ```bash
  145. deno run -A server.ts --categories=sales,inventory,operations --exclude-tools=erpnext_file_upload,erpnext_doc_delete
  146. ```
  147. CLI values override `ERPNEXT_CATEGORIES`, `ERPNEXT_EXCLUDE_CATEGORIES`, and
  148. `ERPNEXT_EXCLUDE_TOOLS` individually. Excluded tools disappear from calls,
  149. viewer actions, and cache warm-up. Use `--flag=value`; invalid exclusions or an
  150. empty server selection fail startup. Full rules:
  151. [tool selection](docs/environment-variables.md#tool-selection).
  152. ## Fresh Instance Setup
  153. A blank ERPNext instance has no master data, so business tools fail validation
  154. until it exists. See
  155. [Seed a blank ERPNext instance](docs/fresh-instance-setup.md).
  156. ## UI Viewers
  157. Nine interactive [MCP Apps](https://github.com/modelcontextprotocol/ext-apps)
  158. viewers, registered as `ui://mcp-erpnext/{name}`:
  159. | Viewer | Description | Interactive Features |
  160. | --------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
  161. | `doc-viewer` | Generic ERPNext document with fields and child tables | Capability-gated attachments, typed navigation, guarded Submit/Cancel, and raw JSON fallback. |
  162. | `doclist-viewer` | Generic document table with sort, filter, pagination, CSV export | Inline details, typed nested navigation, Submit/Cancel, and compact status filters. |
  163. | `invoice-viewer` | Sales Orders, Sales Invoices, and Quotations with line totals | Item, stock, party, and payment navigation plus guarded Submit/Cancel actions. |
  164. | `stock-viewer` | Stock balance table with color-coded qty badges | Item details, recent movements, stock charts, and stock-entry navigation. |
  165. | `chart-viewer` | Universal chart renderer (12 types via Recharts) | Exact point/series navigation and active-context selection across simple and composed charts. |
  166. | `kanban-viewer` | Read-write kanban for Task, Opportunity, Issue | Drag-and-drop, inline editing, serialized saves, and typed related-document navigation. |
  167. | `kpi-viewer` | Big number card with delta, sparkline, trend | Number and trend navigation with bounded active-context selection. |
  168. | `funnel-viewer` | Trapezoid sales funnel with conversion rates | Period-aware stage navigation and bounded active-context selection. |
  169. | `buy-evidence-viewer` | Immutable sealed Buy evidence (recorded session only) | Complete, partial, unresolved, and unavailable projections; no live ERP refresh or mutation. |
  170. Viewers and Buy result fields use the host locale: English, French, Simplified
  171. Chinese, Traditional Chinese, Hindi, Bengali, Tamil and Urdu. Chinese script
  172. tags take precedence over region tags; `zh-TW`, `zh-HK` and `zh-MO` select
  173. Traditional Chinese when no script is specified. Urdu uses right-to-left
  174. document direction, and a later host locale change updates the language and
  175. direction without reloading the viewer. App-level waiting and rejection screens
  176. retain English labels in 3.2; host-context support for those shared surface
  177. screens remains an upstream MCP View follow-up.
  178. ### Navigation and active context
  179. Viewers progressively select the best interaction supported by the host:
  180. - `serverTools` opens typed list, record, and chart targets inside the current
  181. viewer through `app.callServerTool()`. Back and breadcrumb navigation restore
  182. the state of each level.
  183. - `downloadFile` lets the host confirm and save an attachment returned as a
  184. bounded embedded resource. The server also requires the MCP client to announce
  185. the MCP Apps extension and HTML MIME type before serving file bytes. The
  186. viewer never opens an ERPNext file URL directly.
  187. - `updateModelContext` lets chart, KPI, and funnel selections join a bounded
  188. active-context snapshot. The compact context chip keeps up to eight items and
  189. lets users remove one item or clear them all. The snapshot contains selected
  190. values, never hidden instructions for the model.
  191. - `message.text` keeps `app.sendMessage()` as a conversational fallback when
  192. direct navigation or context replacement is unavailable.
  193. - Without these capabilities, local inspection remains available and unsupported
  194. remote actions are omitted.
  195. - The Buy evidence viewer is recorded-session only. It does not call server
  196. tools, refresh live documents, or mutate ERP state.
  197. The server supplies typed navigation metadata and the exact `_availableTools`
  198. allowed for each viewer, so category-filtered deployments do not expose tools
  199. that are not loaded.
  200. ### Refresh model
  201. Read-only viewers revalidate on focus and through their refresh control.
  202. Mutations use an explicit read-only request to fetch committed state; a mutating
  203. tool is never replayed automatically. Overlapping or stale responses are ignored
  204. when a newer host payload or mutation has already won. A confirmed document
  205. change marks every potentially derived snapshot in the current navigation stack
  206. as stale; each marker is removed only when that surface has actually been read
  207. again. Separate MCP Apps are not synchronized automatically in 3.2.
  208. ### Building UI viewers
  209. ```bash
  210. cd src/ui
  211. npm ci
  212. node build-all.mjs
  213. ```
  214. For local iteration, run `deno task ui:dev-host` from the repository root. The
  215. [local test host](src/ui/dev-host/README.md) uses the actual local MCP server
  216. and its built viewers, rebuilding and reloading them without restarting the
  217. desktop client. Open `http://127.0.0.1:5177/?viewer=doclist` for the real
  218. Company list. The host records viewer context updates but has no connected model
  219. or conversation; model consumption and conversational actions require a desktop
  220. host check.
  221. ## Buy evidence capture
  222. **One** read-only tool and **one** recorded App. They do not purchase, create a
  223. BOM/RFQ/PO, refresh live documents, replace generic ERP viewers, or qualify a
  224. live ERPNext instance.
  225. - Tool: `erpnext_buy_capture`. Closed DocTypes only (Item, BOM, Item Price,
  226. Supplier Quotation, Supplier, Price List, UOM, Currency Exchange). Two
  227. `skipCache` reads must agree on `modified` and the closed projection
  228. fingerprint. Return is ephemeral canonical JSON + SHA-256 + byte count. The
  229. caller cannot pass `sourceInstance`, URL, credentials, `capturedAt`, or a
  230. digest. Digital Thread stores those bytes in its own CAS; this server does not
  231. keep a second CAS.
  232. - App: `io.casys.mcp-erpnext.buy-evidence`, App version `3.1.0` (independent of
  233. the package version), resource `ui://mcp-erpnext/buy-evidence-viewer`
  234. (`text/html;profile=mcp-app`), manifest
  235. `ui://mcp-erpnext/buy-evidence-manifest` (`application/json`),
  236. `acceptedActions` = `viewer.session.apply` only. Complete, partial,
  237. unresolved, and unavailable projections stay labelled. No live DocViewer
  238. refresh, mutation, or `app.callServerTool`. Session `anchor` is the sealed
  239. Digital Thread artefact (`provenance.bundleRef`), not a hash of the displayed
  240. projection.
  241. - Schemas: `io.casys.mcp-erpnext.buy-source-capture/1.0`,
  242. `io.casys.mcp-erpnext.buy-recorded-result/1.0` and `/2.0`,
  243. `io.casys.mcp-erpnext.buy-recorded-session/1.0`.
  244. - Result `/2.0` carries bounded `excludedLines` metadata for selected lines
  245. absent from priced `lines`: exact line ID, quantity, unit, and stated reason.
  246. It carries no amount, currency, or price source; covered subtotals remain
  247. sealed values and unresolved lines remain visible.
  248. - The viewer is built with the other MCP Apps
  249. (`cd src/ui && npm ci && node
  250. build-all.mjs`). Published JSR/npm artifacts
  251. include `src/ui/dist/` and the Buy TypeScript module; the HTML resource and
  252. generated manifest are what a published installation serves.
  253. Digital Thread owns configuration/seal (`buy-configuration/1.0`,
  254. `buy-cost-bundle/1.0`, `buy.capture-configuration-cost@1`,
  255. `buy.seal-configuration-cost@1`). A qualified
  256. `commerce.read-erpnext-buy-source@1` binding is required before dispatch.
  257. ## Tools
  258. Record `_list` tools return interactive results via the doclist-viewer with row
  259. click, inline detail, and cross-viewer navigation. The attachment-specific
  260. `erpnext_file_list` tool does not render doclist-viewer. Generic and dedicated
  261. document reads use `doc-viewer`, except Sales Order, Sales Invoice, and
  262. Quotation, which retain the specialized invoice surface.
  263. - **Sales** — Customers, Sales Orders, Invoices, and Quotations with full CRUD,
  264. Submit, and Cancel.
  265. - **Purchasing** — Suppliers, Purchase Orders, Purchase Invoices, Receipts, and
  266. Supplier Quotations.
  267. - **Inventory** — Items, Stock Balance, Warehouses, and Stock Entries.
  268. - **Accounting** — Chart of Accounts, Journal Entries, and Payment Entries.
  269. - **HR** — Employees, Attendance, Leave Applications, Salary Slips, Payroll
  270. Entries, and Expense Claims.
  271. - **Project** — Projects, Tasks (with native assignment), and Timesheets.
  272. - **Delivery** — Delivery Notes and Shipments.
  273. - **Manufacturing** — BOMs, Work Orders, and Job Cards.
  274. - **CRM** — Leads, Opportunities, Contacts, and Campaigns.
  275. - **Assets** — Assets, Movements, Maintenance records, and Categories.
  276. - **Operations** — Generic CRUD, native assignment, attachment listing, upload,
  277. host-mediated download, and deny-by-default Frappe method calls
  278. (`erpnext_doc_*`, `erpnext_file_*`, `erpnext_method_call`).
  279. - **Kanban** — Read-write boards for Task, Opportunity, and Issue with
  280. drag-and-drop.
  281. - **Analytics** — Charts (bar, area, treemap, radar, scatter, P&L…), KPIs with
  282. sparklines, and a sales funnel.
  283. - **Buy** — Read-only sealed capture of closed commercial documents
  284. (`erpnext_buy_capture`) and an immutable recorded-session evidence viewer. Not
  285. a purchase, BOM/RFQ/PO, or live ERP qualification.
  286. - **Setup** — Company creation and assignable user listing.
  287. Full per-tool reference with parameters: [`docs/tools.md`](docs/tools.md).
  288. ## Environment Variables
  289. | Variable | Required | Description |
  290. | ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
  291. | `ERPNEXT_URL` | Yes | ERPNext base URL — self-hosted (e.g. `http://localhost:8000`) or cloud (e.g. `https://mycompany.erpnext.com`) |
  292. | `ERPNEXT_API_KEY` | Yes | API Key from User Settings |
  293. | `ERPNEXT_API_SECRET` | Yes | API Secret from User Settings |
  294. | `ERPNEXT_MAX_UPLOAD_BYTES` | No | Maximum decoded file-upload size in bytes (positive integer; default: 10 MiB) |
  295. | `ERPNEXT_MAX_DOWNLOAD_BYTES` | No | Maximum attachment-download size in bytes (positive integer; default: 10 MiB) |
  296. | `ERPNEXT_METHOD_ALLOWLIST` | No | Comma-separated exact method paths or `prefix.*`; unset means `erpnext_method_call` denies every method, while `*` allows all |
  297. | `MCP_MRTR_SIGNING_KEY` | No | Exactly 64 lowercase hex characters; enables signed ambiguous-link elicitation. **Single-instance deployments only** — see below |
  298. MRTR is opt-in. Without this key, or when the client does not advertise
  299. elicitation, ambiguous links keep returning the existing actionable ambiguity
  300. error instead of prompting for a selection.
  301. > **Do not run MRTR behind a load balancer with this configuration.** The
  302. > signing key proves a retry token is authentic; it does not make it single-use.
  303. > That is the job of a replay store, and the default one is process-local. Share
  304. > the key across two instances and the same signed retry validates on both —
  305. > creating the purchase order, leave application or expense claim **twice**,
  306. > irreversibly once submitted.
  307. >
  308. > A multi-instance deployment must pass a shared atomic `mrtr.replayStore` to
  309. > `McpApp` (Redis satisfies the contract with `SET key 1 NX EXAT`). The
  310. > framework logs a warning at startup whenever MRTR is enabled without one —
  311. > that warning is not noise, it is this paragraph.
  312. ## Architecture
  313. Tools are grouped by business domain under `src/tools/`, the Frappe REST client
  314. is dependency-free, and each UI viewer is a separate build under `src/ui/`. Full
  315. layout: [repository layout](docs/architecture.md).
  316. ## npm Package
  317. The npm package (`@casys/mcp-erpnext`) is a single self-contained bundle with
  318. zero runtime dependencies. UI viewers are embedded. Requires Node >= 20.
  319. ## Contributing
  320. Contributions are welcome — see **[CONTRIBUTING.md](CONTRIBUTING.md)** to get
  321. started, and [AGENTS.md](AGENTS.md) for the full architecture and conventions.
  322. ## License
  323. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.