ERPNext MCP

An ERPNext / Frappe MCP server for AI agents, with native HTTP API access, sensitive-operation approval, and complete request and response storage.

简体中文 ｜ Quick start ｜ Client setup ｜ Usage guide

What it does

• Use REST and RPC without maintaining an MCP whitelist. Call API v1/v2, custom methods, document actions and file endpoints. ERPNext permissions and server-side whitelisted-method rules still apply.
• Review sensitive work with Safe Mode. Prepare an immutable request or batch, obtain one approval for its exact scope, then execute the stored plan.
• Keep large payloads intact. Verify input byte counts, SHA-256 hashes and array lengths; retrieve complete responses through chunked artifacts.
• Keep useful ERP tools close. 31 tools cover documents, schemas, manufacturing preflight, stock, balances, reports and process tracing.

Quick start

Requires Python 3.12 and uv. Run these commands from a local checkout:

git clone https://github.com/Cec1c/ERPNext-MCP.git
cd ERPNext-MCP
uv sync --frozen
Copy-Item .env.example .env

On Linux/macOS, use cp .env.example .env. Edit the new file with your ERPNext URL and credentials:

ERPNEXT_URL=https://your-erpnext.example.com
ERPNEXT_API_KEY=your-api-key
ERPNEXT_API_SECRET=your-api-secret
safe_mode=1

Configure your MCP client using mcp.json, replacing its absolute paths. Set a separate ERPNEXT_ENV_FILE for each site. Dependencies are installed above; startup intentionally skips synchronization:

uv run --no-sync python -u -m erpnext_mcp

This starts a stdio server that waits for the MCP client. Once connected, erpnext_config_status should report version 0.2.0, safe_mode=1 and the intended target. OAuth bearer tokens are also supported through ERPNEXT_ACCESS_TOKEN.

For Codex configuration, multiple instances and Windows startup recovery, see client setup.

Safe Mode

Safe Mode is the default operating model, configured in .env with safe_mode=1.

Operation	safe_mode=1	safe_mode=0
Known read	Execute	Execute
Ordinary document write	Automatic preflight, then execute	Execute directly
Sensitive operation or unknown RPC	Prepare → one approval → execute plan	Execute directly
Input integrity and complete output storage	Enabled	Enabled

Delete, submit/cancel, permission and ledger changes, child-table replacement, mutating batches and unknown side effects are sensitive. A new custom method uses the same confirmation flow without an MCP whitelist edit.

1. Prepare with dry_run=true or erpnext_batch_prepare.
2. Review the target, scope, preflight findings, plan_id and request_sha256.
3. The agent asks the user once for that exact operation or batch; existing explicit approval of the same scope can be reused.
4. Execute through erpnext_plan_execute with the plan ID, hash and actual approval text.

Dry-run is preflight, not a server-side transaction simulation. It does not prove that hooks, stock/accounting posting or external effects will succeed. Confirmation records the agent's attestation of user approval; it cannot independently authenticate a human reply. Batches execute in order and are not atomic.

Complete requests and results

Large inputs use ordered uploads with independently supplied byte counts and SHA-256 hashes. Frozen plans prevent execution from reconstructing a truncated request. Large responses are stored in full and read through erpnext_result_read; paginated APIs still require pagination.

Hashes cannot detect content omitted before the first upload. Preserve source counts and review the prepared scope. Timeouts and incomplete write responses can mean an unknown outcome: inspect the receipt and ERPNext before retrying.

Local .mcp-state/ contains requests, responses and approval records. Keep it private and persistent. The default deployment is stdio for one trusted operator per identity; HTTP hosting needs authentication and isolation in the hosting layer.

Documentation

Task	Guide
Configure clients or repair startup	Client setup
Use tools, files, batches and result artifacts	Usage and operations
Understand supported HTTP behavior and limits	API coverage
Upgrade from 0.1	Migration guide
Review tests and live verification boundaries	Verification evidence

Development

uv sync --frozen
uv run --no-sync pytest -q
uv run --no-sync ruff check src tests
uv run --no-sync ruff format --check src tests
uv build
uv run --no-sync python scripts/check_release.py

CI runs on Windows and Ubuntu. Tests cover MCP stdio handshakes and API/safety contracts; the live read-only probe covered Frappe 16 / ERPNext 16. They do not establish production write behavior or compatibility with every server version.

Built with FastMCP for Frappe's HTTP API.