ERP MCP Server
by jamunachi08
README.md
# ERP MCP Server
Lets outside AI agents (Claude Code, Claude Desktop, Cursor, your own agents) read your ERPNext /
Frappe data through the Model Context Protocol (MCP), with the connected user's own permissions.
It is a companion to the **AI Assistant** app (`omni_ai`) and needs it installed: the tools, the
permission checks, the SQL guard and the audit log are the assistant's, exposed over MCP.
- Works on Frappe / ERPNext v15 and v16, Frappe Cloud, self-hosted and on-premise.
- No extra Python packages, no separate process, no extra port: it is one HTTP endpoint on your site.
- **Read-only.** There are no tools that create, change or delete anything.
- Does not need an AI provider key: the connecting agent brings its own model.
## Install
Install the AI Assistant app first, then:
```bash
bench get-app <url-or-path-of-this-app>
bench --site your-site install-app erp_mcp
```
On Frappe Cloud, add the app to your bench from its Git repository and install it on the site.
## Switch on
1. Open **ERP MCP Settings**.
2. Tick **Enabled**. The form shows the **Endpoint** URL.
3. **Roles**: who may connect. It starts as System Manager only.
4. Choose whether agents may run saved **reports** and **SQL**. SQL additionally needs the user to
hold a role listed under *Roles Allowed to Use SQL* in AI Assistant Settings, and the SQL feature
to be on there.
5. **Max rows per call** (10 to 1000) and **Calls per minute** per user (0 = unlimited).
## Connect an agent
Each person connects as themselves with a Frappe API key: **User → Settings → API Access →
Generate Keys**. The agent then sees exactly what that user may see.
Claude Code:
```bash
claude mcp add --transport http erp https://your-site.example.com/api/method/erp_mcp.api.mcp \
--header "Authorization: token API_KEY:API_SECRET"
```
Any client that takes a JSON configuration:
```json
{
"mcpServers": {
"erp": {
"type": "http",
"url": "https://your-site.example.com/api/method/erp_mcp.api.mcp",
"headers": { "Authorization": "token API_KEY:API_SECRET" }
}
}
}
```
Use a dedicated user with narrow roles for unattended agents, and always HTTPS: the header is a
credential.
## Tools
| Tool | What it does |
|---|---|
| `search_doctypes` | Find DocTypes by name or topic |
| `get_doctype_info` | Fields, links and child tables of a DocType |
| `query_data` | Filtered, grouped, aggregated reads of a DocType |
| `get_document` | One document with its child rows |
| `find_documents` | Search documents by text |
| `list_reports`, `get_report_info`, `run_report` | Saved reports (if allowed) |
| `run_sql` | A guarded read-only SELECT (if allowed, for SQL roles only) |
| `get_result_rows` | More rows of an earlier result, by `result_id` |
Query tools return the first rows plus a `result_id`; the agent pages through the rest with
`get_result_rows`. A user's stored results cannot be read by another user.
## Safety
- Authentication is Frappe's own; a request without valid credentials is refused.
- Every call runs as the connected user: role permissions, User Permissions and field-level
permissions apply. Password and key fields are never returned. Settings DocTypes that hold
credentials are hidden.
- Every tool call is written to **AI Assistant Tool Log** (when logging is on in the assistant).
- Record contents can contain text that tries to steer an agent (prompt injection). This server
cannot change data, but an agent with other tools could be misled; that is the agent's side to
manage.
- Data returned by the tools goes to whatever AI model the connected agent uses.
## Protocol notes
- Streamable HTTP transport with plain JSON responses, protocol versions 2024-11-05, 2025-03-26 and
2025-06-18. No sessions, no server-sent stream (GET returns 405), no JSON-RPC batches.
- Only tools are offered; resources and prompts are empty.
- OAuth sign-in is not implemented. Clients that can only connect through OAuth (for example
connectors added inside the claude.ai web app) cannot use this server; clients that accept a
header can.
## Licence
MIT