<div align="center">

# ERPNext MCP

[![Python 3.12](https://img.shields.io/static/v1?label=Python&message=3.12&color=3776AB&style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
[![FastMCP](https://img.shields.io/static/v1?label=Framework&message=FastMCP&color=2563EB&style=flat-square)](https://gofastmcp.com/)
[![Frappe API v1 and v2](https://img.shields.io/static/v1?label=Frappe%20API&message=v1%20%2F%20v2&color=0089FF&style=flat-square)](docs/api-coverage.md)
[![Safe Mode enabled by default](https://img.shields.io/static/v1?label=Safe%20Mode&message=default%20on&color=16A34A&style=flat-square)](#safe-mode)

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.

[简体中文](README.zh-CN.md) ｜ [Quick start](#quick-start) ｜ [Client setup](docs/client-setup.md) ｜ [Usage guide](docs/usage.md)

</div>

## 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](https://docs.astral.sh/uv/). Run these commands from a local checkout:

```powershell
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:

```dotenv
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](mcp.json), replacing its absolute paths. Set a separate `ERPNEXT_ENV_FILE` for each site. Dependencies are installed above; startup intentionally skips synchronization:

```powershell
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](docs/client-setup.md).

## 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](docs/client-setup.md) |
| Use tools, files, batches and result artifacts | [Usage and operations](docs/usage.md) |
| Understand supported HTTP behavior and limits | [API coverage](docs/api-coverage.md) |
| Upgrade from 0.1 | [Migration guide](docs/migration-0.2.md) |
| Review tests and live verification boundaries | [Verification evidence](docs/refactor-verification.md) |

## Development

```powershell
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](docs/refactor-verification.md).

Built with [FastMCP](https://gofastmcp.com/) for [Frappe's HTTP API](https://docs.frappe.io/framework/user/en/api/rest).