ERPNext MCP

Let AI query ERPNext documents, call Frappe APIs, and execute sensitive operations after explicit approval. Requests, execution plans, and complete results are stored locally for review and tracing.

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

What it does

• Call REST and RPC. Use API v1/v2, custom methods, document actions, and file endpoints under ERPNext permissions and server-side method whitelists. New methods use the existing MCP entry points.
• 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 checks the request and its preconditions; hooks, stock/accounting posting, and external calls run during execution. The agent supplies the approval text, which MCP records without independently authenticating the respondent. Batches execute one operation at a time: if one fails, earlier operations may already have taken effect.

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.

Record source counts before uploading and compare them with the prepared scope; hashes verify the consistency of uploaded content. After a write timeout or incomplete response, inspect the receipt and ERPNext state before deciding whether to retry.

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, covering MCP stdio handshakes and API/safety contracts. The recorded site probe covers read-only calls on Frappe 16 / ERPNext 16. Production writes and other server versions still need live validation; see the verification evidence.

Built with FastMCP for Frappe's HTTP API.