Erpnext_mcp_server

ERPNext MCP Server

Frappe/ERPNext 的框架级 MCP Server——运行方式类似 Doppio CLI，而非针对特定站点。

由 AWS Solution Ltd. 构建 | 联系方式：[email protected]

概述

与典型的、按站点安装的 Frappe 应用不同，此 MCP Server 在 bench 框架级别运行：

• 一个 Server 实例可为 bench 上的所有站点提供服务
• 可通过工具调用动态切换站点上下文
• 无需在每个站点上安装

┌─────────────────────────────────────────────────────┐
│  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                            │
└─────────────────────────────────────────────────────┘

前提条件

• bench 上已安装 Frappe/ERPNext v15+
• Python 3.10+（使用 bench 的虚拟环境）
• 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 客户端

此 Server 使用 STDIO 传输（标准输入/标准输出）。任何支持 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	—	列出此 bench 上的所有站点
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	—	系统和数据库信息
get_versions	—	已安装的应用版本
bench_command	command	运行只读 bench 命令

工作流

工具	参数	描述
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

连接被拒绝

该服务使用 stdio 传输，而非 HTTP。请确保 MCP 客户端通过 stdin/stdout 管道连接。

权限被拒绝

请确保运行该服务的用户拥有以下权限：

• 读取 bench 目录的权限
• 访问该站点数据库的权限
• 执行 bench 命令的权限

许可证

专有 — AWS Solution Ltd.

支持

• 电子邮件：[email protected]
• 问题：在代码仓库中提交 issue

---

基于 Frappe Framework 构建 | MCP Protocol | STDIO Transport