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.

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.