Metadata-Version: 2.4
Name: erpnext-mcp
Version: 0.1.0
Summary: MCP Server for ERPNext REST API
Project-URL: Homepage, https://github.com/ching-tech/erpnext-mcp
Project-URL: Repository, https://github.com/ching-tech/erpnext-mcp
Project-URL: Issues, https://github.com/ching-tech/erpnext-mcp/issues
Author: Ching-Tech
License: MIT License
        
        Copyright (c) 2025 Ching-Tech
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: api,erp,erpnext,frappe,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

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

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