Skip to main content
Glama
ERP MCP Server

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