The ERPNext MCP Server is a Model Context Protocol server that provides comprehensive API access to ERPNext, enabling AI assistants to interact with all aspects of an ERPNext instance.
Document Management (CRUD): Create, read, update, delete, and list documents across any ERPNext DocType with advanced filtering, sorting, pagination, field selection, and OR conditions. Get document counts and summary views with total counts in a single call.
Workflow Operations: Submit and cancel submittable documents like invoices, sales orders, and purchase orders.
Schema & Metadata: List all available DocTypes with optional module filtering, retrieve complete field definitions and metadata for any DocType, and search link field values with autocomplete support.
Inventory Management: Query real-time stock balances from warehouse bins, view stock ledger entries (inventory transaction history), and retrieve item prices from price lists.
Trading & Sales Operations: Convert documents through the sales/purchase cycle (e.g., Quotation → Sales Order → Delivery Note → Invoice) and check outstanding balances for customers and suppliers.
Customer & Supplier Details: Retrieve comprehensive party information including addresses, phone numbers, and contacts with alias search support.
File Management: Upload files from local paths or URLs, list files attached to documents, download files, and get file download URLs.
Reporting & Custom Methods: Execute ERPNext query reports with optional filters and call any whitelisted server-side method with custom arguments using GET or POST requests.
Flexible Integration: Works with any ERPNext instance via API keys and can be configured for MCP clients like Claude Desktop.
Provides tools to interact with an ERPNext instance via its REST API, allowing for document management (CRUD), workflow actions like submitting and cancelling documents, running query reports, inspecting schemas, and accessing specialized inventory and trading functions like stock balances and party balances.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ERPNext MCP ServerShow me the current stock balance for item 'iPhone 15' in the Main Warehouse"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 syncRun
set -a && source .env && set +a && uv run erpnext-mcpAvailable Tools
Tool | Description |
| List documents with filters, sorting, pagination |
| Get a single document by name |
| Create a new document |
| Update an existing document |
| Delete a document |
| Submit a submittable document |
| Cancel a submitted document |
| Execute an ERPNext report |
| Get document count with optional filters |
| List documents with total count |
| Call any whitelisted server-side method |
| Link field autocomplete search |
| List all available DocType names |
| Get field definitions for a DocType |
| Real-time stock balance from Bin |
| Stock ledger entries (inventory history) |
| Item prices from price lists |
| Document conversion (e.g. SO → DN) |
| Outstanding balance for Customer/Supplier |
| Get supplier with address, phone, contacts (supports alias search) |
| Get customer with address, phone, contacts (supports alias search) |
| Upload a local file to ERPNext (by file path) |
| Upload a file from URL |
| List files attached to a document |
| Download a file by 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 modelsLicense
MIT