README.md
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 |
get_stock_ledger |
Stock ledger entries (inventory history) |
get_item_price |
Item prices from price lists |
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
Tools 10
list_documentsList documents with filters, sorting, paginationget_documentGet a single document by namecreate_documentCreate a new documentupdate_documentUpdate an existing documentdelete_documentDelete a documentsubmit_documentSubmit a submittable documentcancel_documentCancel a submitted documentrun_reportExecute an ERPNext reportget_stock_balanceReal-time stock balance from Binget_supplier_detailsGet supplier with address, phone, contactsEnvironment Variables
ERPNEXT_URLrequiredThe base URL of your ERPNext instanceERPNEXT_API_KEYrequiredAPI key for authenticationERPNEXT_API_SECRETrequiredAPI secret for authenticationTry it
→List the last 5 sales orders created in the system.
→What is the current stock balance for the item 'Widget-001'?
→Create a new customer named 'Acme Corp' with the provided contact details.
→Get the outstanding balance for supplier 'Global Supplies'.
→Run the 'General Ledger' report for the current month.