erpnext-mcp 0.5.0

MCP Server for ERPNext REST API

ERPNext MCP Server

MCP (Model Context Protocol) server for ERPNext REST API, built with FastMCP and Python.

Features

• CRUD — List, get, create, update, delete documents
• Workflow — Submit and cancel submittable documents
• Reports — Run ERPNext query reports
• Schema — Inspect DocType field definitions, list all DocTypes
• Inventory — Stock balance, stock ledger, item prices
• Trading — Document conversion (e.g. Quotation → Sales Order), party balance
• Supplier/Customer — Get complete details with address, phone, contacts; supports alias search
• Files — Upload, list, download files
• Helpers — Link search (autocomplete), document count, generic method calls

Requirements

• Python >= 3.11
• uv (recommended) or pip
• ERPNext instance with API key/secret

Setup

# Clone the repo
git clone <repo-url> && cd erpnext-mcp

# Create .env file
cat > .env << 'EOF'
ERPNEXT_URL=https://your-erpnext-instance.com
ERPNEXT_API_KEY=your_api_key
ERPNEXT_API_SECRET=your_api_secret
EOF

# Install dependencies
uv sync

Run

set -a && source .env && set +a && uv run erpnext-mcp

Available Tools

Tool	Description
list_documents	List documents with filters, sorting, pagination
get_document	Get a single document by name
create_document	Create a new document
update_document	Update an existing document
delete_document	Delete a document
submit_document	Submit a submittable document
cancel_document	Cancel a submitted document
run_report	Execute an ERPNext report
get_count	Get document count with optional filters
get_list_with_summary	List documents with total count
run_method	Call any whitelisted server-side method
search_link	Link field autocomplete search
list_doctypes	List all available DocType names
get_doctype_meta	Get field definitions for a DocType
get_stock_balance	Real-time stock balance from Bin (exact item_code)
get_stock_ledger	Stock ledger entries (exact item_code)
get_item_price	Item prices from price lists (exact item_code)
find_items	Fuzzy-search Item across name / item_name / item_code
get_item_details	Item master + stock + price in one call (supports keyword)
make_mapped_doc	Document conversion (e.g. SO → DN)
get_party_balance	Outstanding balance for Customer/Supplier
get_supplier_details	Get supplier with address, phone, contacts (supports alias search)
get_customer_details	Get customer with address, phone, contacts (supports alias search)
upload_file	Upload a local file to ERPNext (by file path)
upload_file_from_url	Upload a file from URL
list_files	List files attached to a document
download_file	Download a file by URL
get_file_url	Get download URL for a file

MCP Client Configuration

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

{
  "mcpServers": {
    "erpnext": {
      "command": "uv",
      "args": ["--directory", "/path/to/erpnext-mcp", "run", "erpnext-mcp"],
      "env": {
        "ERPNEXT_URL": "https://your-erpnext-instance.com",
        "ERPNEXT_API_KEY": "your_api_key",
        "ERPNEXT_API_SECRET": "your_api_secret"
      }
    }
  }
}

Project Structure

src/erpnext_mcp/
├── server.py   # MCP tool definitions (FastMCP)
├── client.py   # ERPNext REST API client (httpx async)
└── types.py    # Pydantic models

License

MIT