Erpnext_mcp_server

ERPNext MCP サーバー

Frappe/ERPNext 向けのフレームワークレベルの MCP サーバーです。Doppio CLI のように動作し、特定のサイトに依存しません。

AWS Solution Ltd. が開発 | お問い合わせ：[email protected]

概要

サイトごとにインストールする一般的な Frappe アプリとは異なり、この MCP サーバーはベンチのフレームワークレベルで実行されます。

• 1 つのサーバーインスタンスでベンチ上のすべてのサイトに対応します
• ツール呼び出しによってサイトのコンテキストが動的に切り替わります
• 各サイトへのインストールは不要です

┌─────────────────────────────────────────────────────┐
│  MCP Client (Claude, Hermes, etc.)                 │
│  (running on another machine)                        │
└────────────────────┬────────────────────────────────┘
                     │ stdio
┌────────────────────▼────────────────────────────────┐
│  ERPNext MCP Server                                 │
│  (this bench)                                       │
│                                                     │
│  • list_sites     → all bench sites               │
│  • switch_site    → change context                 │
│  • get_document   → query current site             │
│  • execute_sql    → safe SELECT queries            │
│  • bench_command  → read-only bench operations     │
│  • ... + 15 more tools                            │
└─────────────────────────────────────────────────────┘

前提条件

• ベンチに Frappe/ERPNext v15+ がインストールされていること
• Python 3.10+（ベンチの仮想環境を使用）
• MCP クライアント（Claude Code、Hermes Agent など）

クイックスタート

1. Python 環境を確認する

cd ~/frappe-bench
./env/bin/python --version  # Should be Python 3.10+

2. ローカルでテストする

# Set your default site
export FRAPPE_SITE=your-site.domain.com
export BENCH_PATH=/path/to/your/frappe-bench

# Run the server
./env/bin/python -m erpnext_mcp_server.mcp.server

3. MCP クライアントを設定する

Claude Code の場合

プロジェクト内の .mcp.json に追加します。

{
  "mcpServers": {
    "erpnext": {
      "command": "python",
      "args": ["-m", "erpnext_mcp_server.mcp.server"],
      "env": {
        "FRAPPE_SITE": "your-site.domain.com",
        "BENCH_PATH": "/home/youruser/frappe-bench"
      }
    }
  }
}

Hermes Agent の場合

Hermes の設定に追加します。

mcp_servers:
  erpnext:
    command: ssh
    args:
      - user@your-server
      - 'cd /path/to/bench && FRAPPE_SITE=your-site.com ./env/bin/python -m erpnext_mcp_server.mcp.server'

その他の MCP クライアントの場合

このサーバーはSTDIO トランスポート（stdin/stdout）を使用します。stdio に対応する MCP クライアントであれば、どれでも動作します。

{
  "mcpServers": {
    "erpnext": {
      "command": "/path/to/frappe-bench/env/bin/python",
      "args": ["-m", "erpnext_mcp_server.mcp.server"],
      "env": {
        "FRAPPE_SITE": "your-site.domain.com",
        "BENCH_PATH": "/path/to/frappe-bench"
      }
    }
  }
}

利用可能なツール

サイト管理

ツール	引数	説明
list_sites	—	このベンチ上のすべてのサイトを一覧表示します
switch_site	site	別のサイトに切り替えます
current_site	—	現在のサイト名を取得します

ドキュメントの CRUD

ツール	引数	説明
get_document	doctype, name	ID でドキュメントを取得します
list_documents	doctype, filters?, limit?	フィルターを指定してドキュメントを一覧表示します
create_document	doctype, data	新しいドキュメントを作成します
update_document	doctype, name, data	既存のドキュメントを更新します
delete_document	doctype, name	ドキュメントを削除／キャンセルします
count_documents	doctype, filters?	条件に一致するドキュメント数を数えます

メタデータ

ツール	引数	説明
list_doctypes	module?	すべての DocType を一覧表示します
get_doctype_meta	doctype	フィールド定義を取得します

データベース

ツール	引数	説明
execute_sql	query, limit?	SELECT クエリを実行します（安全）
get_table_info	table	テーブル構造を取得します

システム情報

ツール	引数	説明
get_system_info	—	システムと DB の情報を取得します
get_versions	—	インストール済みアプリのバージョンを取得します
bench_command	command	読み取り専用のベンチコマンドを実行します

ワークフロー

ツール	引数	説明
submit_document	doctype, name	ドキュメントを提出します（docstatus 0→1）
cancel_document	doctype, name	提出済みドキュメントをキャンセルします

検索

ツール	引数	説明
search	query, doctype?, limit?	DocType 全体を検索します

ファイル

ツール	引数	説明
read_file	path, lines?	ファイルを読み取ります（安全なパスのみ）
list_files	path, recursive?	ディレクトリを一覧表示します

使用例

Python クライアントのテスト

import subprocess
import json

proc = subprocess.Popen(
    ["./env/bin/python", "-m", "erpnext_mcp_server.mcp.server"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    cwd="/path/to/frappe-bench",
    env={"FRAPPE_SITE": "your-site.domain.com"}
)

# Initialize
init_msg = {
    "jsonrpc": "2.0", "id": 1,
    "method": "initialize",
    "params": {
        "protocolVersion": "2024-11-05",
        "capabilities": {},
        "clientInfo": {"name": "test", "version": "1.0"}
    }
}
proc.stdin.write((json.dumps(init_msg) + "\n").encode())
proc.stdin.flush()

# List sites
list_msg = {
    "jsonrpc": "2.0", "id": 2,
    "method": "tools/call",
    "params": {"name": "list_sites", "arguments": {}}
}
proc.stdin.write((json.dumps(list_msg) + "\n").encode())
proc.stdin.flush()

proc.stdin.close()
print(proc.stdout.read().decode())

Claude Code の使用方法

設定が完了したら、Claude に尋ねるだけです。

> List all customers in ERPNext
> Create a new Sales Order for customer ABC
> What is the total outstanding for Invoice INV-001?

Claude は MCP ツールを使用して、ERPNext に直接問い合わせます。

アーキテクチャ

erpnext_mcp_server/
├── __init__.py
├── hooks.py
├── mcp/
│   ├── __init__.py
│   ├── __main__.py          # Entry point
│   ├── server.py            # Main MCP server
│   └── config.py            # Configuration
└── doctype/                 # Settings DocTypes (optional)

設計原則

1. フレームワークレベル — サイトごとではなく、bench レベルで動作します
2. 遅延読み込み — 必要な場合にのみ Frappe をインポートします
3. サイトコンテキスト — ツール呼び出しごとにコンテキストを動的に切り替えます
4. セキュリティ優先 — SQL は SELECT のみに制限され、ファイルへのアクセスは安全なパスに制限されます

セキュリティ

制限	詳細
SQL	SELECT クエリのみ許可
ファイル	sites/、apps/、logs/、config/ のパスのみ
Bench コマンド	読み取り専用操作のみ
サイトアクセス	Frappe の権限によって適用されます

環境変数

変数	必須	デフォルト	説明
FRAPPE_SITE	はい	—	デフォルトのサイト名
BENCH_PATH	いいえ	/home/frappe/frappe-bench	Bench ディレクトリ
FRAPPE_STREAM_LOGGING	いいえ	1	ファイルログを無効化

トラブルシューティング

「site does not exist」エラー

# Verify site exists
ls ~/frappe-bench/sites/  | grep your-site

# Check site config
cat ~/frappe-bench/sites/your-site.domain.com/site_config.json

接続が拒否される

サーバーは HTTP ではなく、stdio トランスポートを使用します。MCP クライアントが stdin/stdout パイプ経由で接続していることを確認してください。

権限が拒否される

サーバーを実行するユーザーに、以下の権限があることを確認してください。

• bench ディレクトリへの読み取りアクセス
• サイトのデータベースへのアクセス
• bench コマンドの実行権限

ライセンス

プロプライエタリ — AWS Solution Ltd.

サポート

• メール：[email protected]
• 問題：リポジトリで Issue を作成してください

---

Frappe Framework で構築 | MCP Protocol | STDIO Transport