Paperware MCP Server (paperware_mcp)

A native Model Context Protocol (MCP) Server for the ERPNext/Frappe bench of Paperware Factory (erp.paperwarefactory.com).

This app enables the Prime AI Agent (NousResearch Hermes Agent framework, "Prime" persona, hosted on Docker/Coolify) to communicate with ERPNext directly using the Frappe ORM.

🌟 Key Features

1. Direct Frappe ORM Integration: No external HTTP REST API calls or API Key/Secret required. Directly uses frappe.get_doc, frappe.get_list, doc.insert(), doc.submit(), doc.cancel(), etc.

2. Per-Request Permission Impersonation: On each tool call, frappe.set_user() is performed according to the requesting_user parameter, and the actual Frappe permission engine takes effect.

3. Whitelisted Execution Security: The call_method tool can only execute functions decorated with @frappe.whitelist(). Unauthorized Python code execution is completely secured and blocked.

4. FastMCP Integration: Tool setup based on FastMCP from the Python mcp>=1.9.0,<2.0.0 package. Both stdio and sse transport options are available.

5. Native Bench Command: Integrated with the Frappe CLI — the service can be started via the command bench --site erp.paperwarefactory.com paperware-mcp.

Related MCP server: MCP Task

🛠️ Installation Guide (Step-by-Step Installation)

Step 1: Place the App Source

Go to your Frappe Bench directory (/home/prime/frappe-bench/) and ensure the app is present in the apps/paperware_mcp folder.

cd /home/prime/frappe-bench

Step 2: Install Python Dependencies

Install the required packages (mcp>=1.9.0,<2.0.0) in the Bench Virtual Environment:

./env/bin/pip install -r apps/paperware_mcp/requirements.txt

Step 3: Install the App on the ERPNext Site

Install the paperware_mcp app on your desired site:

bench --site erp.paperwarefactory.com install-app paperware_mcp

🚀 Service Run and Command Usage (Usage & Command Options)

The following options can be used to run the paperware-mcp CLI command:

[!WARNING] --default-user Administrator should not be used in production. In production, you must pass the email of a specific bot user.

Command Examples:

1. Running in Standard Input/Output (stdio) mode:

bench --site erp.paperwarefactory.com paperware-mcp --transport stdio --default-user hermes.bot@paperwarefactory.com

2. Running in Server-Sent Events (SSE) mode on a specific port:

bench --site erp.paperwarefactory.com paperware-mcp --transport sse --port 8931 --default-user hermes.bot@paperwarefactory.com

🛡️ Creating a Dedicated Hermes Bot User (Security Best Practices)

It is recommended to create a dedicated Bot User in ERPNext for working in a production environment:

1. Go to User List in ERPNext Desk and create a New User.

2. Email: hermes.bot@paperwarefactory.com

3. First Name: Hermes Bot

4. Role Profile: Provide only the necessary roles (e.g., Stock User, Sales User, Accounts User) so that the Hermes Agent does not get unnecessary administrative power.

5. Use the --default-user hermes.bot@paperwarefactory.com flag when starting the server.

🏭 Production Deployment

Use Supervisor or a Systemd service to automatically start and keep the service running in the background.

Method 1: Supervisor Configuration

Create the file /etc/supervisor/conf.d/paperware_mcp.conf and write the following code:

[program:paperware-mcp]
command=/home/prime/frappe-bench/env/bin/bench --site erp.paperwarefactory.com paperware-mcp --transport sse --port 8931 --default-user hermes.bot@paperwarefactory.com
directory=/home/prime/frappe-bench
user=prime
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
stdout_logfile=/home/prime/frappe-bench/logs/paperware_mcp.out.log
stderr_logfile=/home/prime/frappe-bench/logs/paperware_mcp.err.log
environment=PATH="/home/prime/frappe-bench/env/bin:%(ENV_PATH)s"

Reload and start the configuration:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl status paperware-mcp

Method 2: Systemd Unit Configuration

Create the file /etc/systemd/system/paperware-mcp.service and provide the following configuration:

[Unit]
Description=Paperware MCP Server for Hermes AI Agent
After=network.target redis-server.service mariadb.service

[Service]
Type=simple
User=prime
WorkingDirectory=/home/prime/frappe-bench
ExecStart=/home/prime/frappe-bench/env/bin/bench --site erp.paperwarefactory.com paperware-mcp --transport sse --port 8931 --default-user hermes.bot@paperwarefactory.com
Restart=always
RestartSec=5
StandardOutput=append:/home/prime/frappe-bench/logs/paperware_mcp.out.log
StandardError=append:/home/prime/frappe-bench/logs/paperware_mcp.err.log

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable paperware-mcp
sudo systemctl start paperware-mcp
sudo systemctl status paperware-mcp

🤖 Hermes Agent MCP Client Config

How to add paperware_mcp to the mcp_config.json file of Hermes Agent (or any MCP Client):

1. For SSE Transport (recommended for Docker/remote connections):

{
  "mcpServers": {
    "paperware_mcp": {
      "url": "http://erp.paperwarefactory.com:8931/sse"
    }
  }
}

2. For Stdio Transport (for same container/local execution):

{
  "mcpServers": {
    "paperware_mcp": {
      "command": "/home/prime/frappe-bench/env/bin/bench",
      "args": [
        "--site",
        "erp.paperwarefactory.com",
        "paperware-mcp",
        "--transport",
        "stdio",
        "--default-user",
        "hermes.bot@paperwarefactory.com"
      ]
    }
  }
}

📦 Total Tools (Exposed MCP Tools - 15 Tools)

📄 License

MIT License — © 2026 Prime Technology of Bangladesh