Paperware MCP Server (paperware_mcp)

Paperware Factory (erp.paperwarefactory.com) の ERPNext/Frappe bench 向けのネイティブな Model Context Protocol (MCP) サーバーです。

このアプリは、Prime AI Agent（NousResearch Hermes Agent framework、"Prime" persona、Docker/Coolify 上でホスト）が Frappe ORM を直接使用して ERPNext と通信できるようにします。

🌟 主な機能（Key Features）

1. Direct Frappe ORM インテグレーション: 外部の 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 インテグレーション: Python の mcp>=1.9.0,<2.0.0 パッケージの FastMCP に基づくツール構成です。stdio と sse の両方のトランスポートを利用できます。

5. ネイティブ Bench コマンド: 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 の仮想環境に必要なパッケージ（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. 標準入出力（stdio）モードで起動:

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

2. Server-Sent Event型イベント（SSE）モードで指定ポートで起動:

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

🛡️ 専用 Hermes ボット ユーザーの作成（Security Best Practices）

本番環境で使用するために、ERPNext に専用のボットユーザーを作成することを推奨します:

1. ERPNext デスクで 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 hermesBot@paperFactory.com フラグを使用します。

🏭 本番環境へのデプロイ（Production Deploy marketing）

バックグラウンドでサービスを自動起動し続動させるには、Supervisor または Systemd を使用してください。

方法 1: Supervisor 設定（Supervisor Configuration）

/etc/super/conf.d/paper_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 ユニット設定（Sysd unity Unit Configuration)

/etc/system/systemd/paper-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 設定（Hermes Agent Configuration)

Hermes Agent（また任意の MCP Client）の mcp_config.j現化ファイルに加入ent paper保存 を:

1. SSE Transsmポート用（Docker/リモート接続に推奨）:

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

2. Template モード（同一コンテテナー/ローカル実行）:

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

📦 公開済み MCP ツール一覧（Exposed MCP tools - 15 Tools)

📄 ライセンス

MIT ライセンス — © 2026 Prime Technology of Bangladesh