ERPNext

You can run an MCP server that exposes ERPNext REST API operations, enabling you to perform CRUD actions, workflow operations, reports, and inventory queries directly through a unified protocol. This server acts as a bridge between ERPNext and MCP clients, making it straightforward to automate and integrate ERPNext data workflows.

How to use

To use the ERPNext MCP Server, first configure the server so your ERPNext instance is reachable by the MCP client. You will typically supply your ERPNext instance URL and API credentials, start the MCP server, and then connect with an MCP client to perform operations such as listing, creating, updating, or deleting documents; running reports; and querying stock, prices, and party balances.

How to install

Prerequisites you need before installing include Python 3.11 or newer and the MCP runtime tooling. You should also have access to an ERPNext instance with API keys.

# Clone the repository
git clone <repo-url> && cd erpnext-mcp

# Create a configuration file with ERPNext connection details
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 and set up the MCP environment
uv sync

Start the MCP server using the runtime command shown in the configuration example. This runs the server in the foreground and uses the environment variables from your .env file.

set -a && source .env && set +a
uv run erpnext-mcp

Configuration to run the server

You configure the MCP client to connect to the ERPNext MCP Server by providing a local stdio configuration that tells the client how to start the server and which environment variables to use.

{
  "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"
      }
    }
  }
}

What you can do with the server

The ERPNext MCP Server exposes a rich set of capabilities. You can perform CRUD operations on ERPNext documents, submit and cancel submittable documents, run ERPNext query reports, inspect DocType definitions, view stock balances and ledgers, fetch item prices, and retrieve detailed supplier and customer information including addresses and contacts. You can also upload and download files, perform link autocomplete searches, and call whitelisted server-side methods.

Additional notes

Environment variables are required for connecting to ERPNext and should be kept secure. Use the standard security practices for API keys, including rotation and restricted scopes. When testing locally, ensure your ERPNext instance is reachable from the host running the MCP server, and that any firewalls or VPNs allow API traffic.

Tools and endpoints you get from the server

The server provides a broad set of functions to interact with ERPNext data. These include tools for listing, retrieving, creating, updating, and deleting documents; submitting and canceling workflows; running reports; and obtaining metadata, stock information, prices, party balances, and file operations. You can also perform document conversions and access detailed supplier and customer records.

Available tools

list_documents

List documents with optional filters, sorting, and pagination.

get_document

Retrieve a single document by its name.

create_document

Create a new ERPNext document.

update_document

Update fields on an existing ERPNext document.

delete_document

Delete a document from ERPNext.

submit_document

Submit a submittable document to move it through workflow.

cancel_document

Cancel a submitted document.

run_report

Execute an ERPNext report and fetch results.

get_count

Get the count of documents matching filters.

get_list_with_summary

List documents with a total count summary.

run_method

Call a whitelisted server-side method.

search_link

Autocomplete search for link fields.

list_doctypes

List all available DocType names.

get_doctype_meta

Get field definitions for a DocType.

get_stock_balance

Fetch real-time stock balance from Bin.

get_stock_ledger

Retrieve stock ledger entries for inventory history.

get_item_price

Fetch item prices from price lists.

make_mapped_doc

Convert documents (e.g., Sales Order to Delivery Note).

get_party_balance

Get outstanding balance for Customer or Supplier.

get_supplier_details

Get supplier details with address and contacts (supports alias search).

get_customer_details

Get customer details with address and contacts (supports alias search).

upload_file

Upload a local file to ERPNext by path.

upload_file_from_url

Upload a file to ERPNext from a URL.

list_files

List files attached to a document.

download_file

Download a file by URL.

get_file_url

Get a download URL for a file.