erpnext-mcp-native

An in-process MCP server for ERPNext — install it as a Frappe app and Claude, ChatGPT, and n8n get 16 read-only ERP tools over JSON-RPC, authenticated by OAuth 2.0 or a simple API key. No separate process, no REST proxying: tools run inside your bench with direct ORM access and your site's own permission system.

Why this instead of…?

• vs. frappe/mcp — that's the official framework for building MCP servers into Frappe apps. This is a ready-made ERPNext toolset: install and go. (Building this app on that framework is a possible future direction.)

• vs. standalone MCP servers (TypeScript/Python processes calling ERPNext over REST) — no extra process to run, no second credential to manage, and per-user authorization is enforced by Frappe itself, not re-implemented.

Related MCP server: MCP Task

Install

Tested on ERPNext/Frappe v16 (v15 untested).

bench get-app --skip-assets https://github.com/mdad-elec/erpnext-mcp-native
bench --site your-site.example.com install-app erpnext_mcp_native
bench --site your-site.example.com execute erpnext_mcp_native.setup.setup_mcp

Why --skip-assets: the app is pure Python with no frontend assets, and on bench 5.29.1 the post-clone asset build runs before the app is registered — frappe's bundler cannot resolve an unregistered app and the install aborts. The flag skips that step; nothing is lost for an asset-less app.

bench 5.29.1 registration gap: get-app --skip-assets may write sites/apps.json but not append sites/apps.txt. If install-app then errors with the app "not in apps.txt", append the line erpnext_mcp_native to sites/apps.txt yourself and re-run install-app. ⚠️ First check the file ends with a newline — appending to a file whose last line lacks one fuses two app names onto a single line (e.g. paymentserpnext_mcp_native), which breaks the bench's app list.

The last step creates the MCP User role and a connector user, generates an API key/secret pair, and prints it exactly once — the secret is stored encrypted and cannot be shown again. It is idempotent: re-running never rotates existing credentials. Optional: pass a connector email with bench --site <site> execute erpnext_mcp_native.setup.setup_mcp --args '["mcp@your-domain.example"]'.

Endpoints

Access requires role System Manager or MCP User.

Quick check:

curl -s -X POST https://your-site.example.com/api/method/erpnext_mcp_native.api.handle_mcp \
  -H "X-Frappe-API-Key: <key>:<secret>" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

python3 scripts/smoke.py https://your-site.example.com <key>:<secret> verifies a full install (handshake, 16-tool parity, one call per tool class).

Tools (16)

get_system_health · get_entity_counts · search_doctypes · get_doctype_info · analyze_doctype · global_search · query_doctype · query_with_aggregation · get_sales_summary · get_stock_balance · get_outstanding_invoices · get_profit_analysis · get_pending_approvals · get_linked_documents · get_document_pdf · run_report — see docs/tools.md for schemas and argument-shape pitfalls.

Docs

• docs/tools.md — tool reference + argument pitfalls

• docs/oauth.md — Claude.ai / ChatGPT connector setup

• docs/n8n.md — n8n / automation setup

• docs/runbook.md — permissions model, telemetry, credential rotation

Telemetry

Every tool call is logged as one JSON line to logs/mcp_usage.log inside the bench: tool, user, duration ms, ok/fail, error text. Absent-by-default nowhere — it's on.

Related

Deskpilot — the same problem approached from the other side. This server points ERPNext outward, so an external agent can reach your data. Deskpilot puts an assistant inside the Desk, where it drives the screen and fills the form in front of the user. They compose: run both and the same ERP answers an agent over MCP and a user at their keyboard.

License

MIT.