erpnext-fast-mcp-server

A FastMCP server that exposes generic ERPNext / Frappe DocType operations as MCP tools, so any MCP-compatible client (Claude Desktop, Claude Code, etc.) can read and write data in an ERPNext site over its REST API.

Tools

• get_document(doctype, name) — fetch a single document

• list_documents(doctype, filters, fields, order_by, limit, limit_start) — search/list documents

• create_document(doctype, data) — create a document

• update_document(doctype, name, data) — update fields on a document

• delete_document(doctype, name) — delete a document

• get_doctype_meta(doctype) — fetch a DocType's field/schema definition

• get_count(doctype, filters) — count documents matching filters

• run_report(report_name, filters) — run a Query/Script report

These are generic, so they work against any DocType (Customer, Sales Invoice, Item, Stock Entry, etc.) without hardcoding business objects.

Related MCP server: ERPNext MCP Server

Setup

1. Install dependencies (using uv):

   uv sync

2. Get API credentials from your Frappe/ERPNext site: User → API Access → Generate Keys. Copy the API Key and API Secret shown (the secret is only displayed once).

3. Copy .env.example to .env and fill in your values:

   cp .env.example .env

   FRAPPE_URL=https://your-site.frappe.cloud
   FRAPPE_API_KEY=your-api-key
   FRAPPE_API_SECRET=your-api-secret

   .env is git-ignored — never commit real credentials.

4. Run the server directly to check it starts:

   uv run erpnext-mcp

Using with Claude Desktop / Claude Code

Add to your MCP client config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "erpnext": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/erpnext-fast-mcp-server", "erpnext-mcp"],
      "env": {
        "FRAPPE_URL": "https://your-site.frappe.cloud",
        "FRAPPE_API_KEY": "your-api-key",
        "FRAPPE_API_SECRET": "your-api-secret"
      }
    }
  }
}

Alternatively, keep credentials only in .env (not in the client config) and omit the env block above — python-dotenv will load .env from the project directory at startup.

Security notes

• Never commit .env or hardcode API keys/secrets in source.

• Scope the Frappe user's role/permissions to the minimum needed — the MCP tools inherit whatever permissions the API key's user has on the site.

• delete_document is irreversible; consider removing it from the tool list if you don't want an MCP client to be able to delete records.