Paperware MCP Server (paperware_mcp)

为 Paperware Factory（erp.paperwarefactory.com）的 ERPNext/Frappe bench 提供的原生 Model Context Protocol（MCP）Server。

此应用使 Prime AI Agent（NousResearch Hermes Agent framework，"Prime" persona，托管于 Docker/Coolify）能够直接使用 Frappe ORM 与 ERPNext 通信。

🌟 核心特性（Key Features）

1. Direct Frappe ORM Integration：无需任何外部 HTTP REST API 调用或 API Key/Secret。直接使用 frappe.get_doc、frappe.get_list、doc.insert()、doc.submit()、doc.cancel() 等。

2. Per-Request Permission Impersonation：每次工具调用时根据 requesting_user 参数执行 frappe.set_user()，并让真实的 Frappe 权限引擎生效。

3. Whitelisted Execution Security：call_method 工具只能运行带有 @frappe.whitelist() 装饰器的函数。未经授权的 Python 代码执行完全受到保护并被阻止。

4. FastMCP Integration：基于 Python mcp>=1.9.0,<2.0.0 包中的 FastMCP 进行工具设置。同时支持 stdio 和 sse 两种传输方式。

5. Native Bench Command：与 Frappe CLI 集成 — 可通过 bench --site erp.paperwarefactory.com paperware-mcp 命令启动服务。

Related MCP server: MCP Task

🛠️ 安装指南（Step-by-Step Installation）

步骤 1：放置应用源码

进入您的 Frappe Bench 目录（/home/prime/frappe-bench/），确保应用已存在于 apps/paperware_mcp 文件夹中。

cd /home/prime/frappe-bench

步骤 2：安装 Python 依赖

在 Bench 虚拟环境中安装必需的 packages（mcp>=1.9.0,<2.0.0）：

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

步骤 3：在 ERPNext 站点上安装应用

在您指定的站点上安装 paperware_mcp 应用：

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

🚀 服务运行与命令用法（Usage & Command Options）

运行 paperware-mcp CLI 命令时，可以使用以下选项：

[!WARNING] 生产环境中不应使用 --default-user Administrator。在生产环境中，必须传入一个专用的机器人用户邮箱。

命令示例：

1. 以 Standard Input/Output（stdio）模式运行：

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

2. 以 Server-Sent Events（SSE）模式在指定端口运行：

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

🛡️ 创建专用 Hermes Bot 用户（Security Best Practices）

建议在生产环境中于 ERPNext 内创建一个专用的 Bot User：

1. 在 ERPNext Desk 中进入 User List，创建 New User。

2. Email：hermes.bot@paperwarefactory.com

3. First Name：Hermes Bot

4. Role Profile：仅授予必要的角色（例如：Stock User、Sales User、Accounts User），以确保 Hermes Agent 不会获得不必要的管理权限。

5. 启动服务器时，请使用 --default-user hermes.bot@paperwarefactory.com 标志。

🏭 生产部署（Production Deployment）

请使用 Supervisor 或 Systemd 服务，让服务在后台自动启动并持续运行。

方法 1：Supervisor Configuration（Supervisor 配置）

创建 /etc/supervisor/conf.d/paperware_mcp.conf 文件并写入以下代码：

[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"

重新加载并启动配置：

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

方法 2：Systemd Unit Configuration（Systemd 服务）

创建 /etc/systemd/system/paperware-mcp.service 文件并给出以下配置：

[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

启用并启动服务：

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

🤖 Hermes Agent MCP Client Config（Hermes Agent 配置）

向 Hermes Agent（或任何 MCP Client）的 mcp_config.json 文件中添加 paperware_mcp 的规则：

1. 适用于 SSE Transport（推荐用于 Docker/远程连接）：

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

2. 适用于 Stdio Transport（同一容器/本地执行的情况）：

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

📦 全部工具（Exposed MCP Tools - 15 Tools）

📄 许可证

MIT License — © 2026 Prime Technology of Bangladesh