# ERPNext MCP Server
MCP (Model Context Protocol) server for ERPNext REST API, built with [FastMCP](https://github.com/jlowin/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](https://docs.astral.sh/uv/) (recommended) or pip
- ERPNext instance with API key/secret
## Setup
```bash
# 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
```bash
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`):
```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
