Skip to main content
Glama
ERPNext MCP Server

ERPNext MCP Server

by 000sami000
README.md
# 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
uv run erpnext-mcp
```

The Streamable HTTP MCP endpoint is available at `http://127.0.0.1:8000/mcp`
by default. Configure `ERPNEXT_MCP_HOST`, `ERPNEXT_MCP_PORT`, and
`ERPNEXT_MCP_PATH` in `.env` to change it. For a public deployment, bind to an
appropriate interface and place the service behind an HTTPS reverse proxy.

## 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

Start the server, then add its HTTP endpoint to your MCP client (for example,
Claude Desktop's `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "erpnext": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}
```

## 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