ERPNext MCP服务器
用于ERPNext集成的模型上下文协议服务器,具有全面的自定义应用程序开发功能
这是一个基于类型脚本的MCP服务器,提供与ERPNext/Frappe API的全面集成。它使AI助手能够通过模型上下文协议与ERPNext数据和功能进行交互,包括创建自定义DocType、子表、模块、仪表板、工作流、脚本、Webhook、报告、图表、网页等的能力。
特性
资源
- 通过以下方式访问ERPNext文档
erpnext://{doctype}/{name}URI - 用于结构化数据访问的JSON格式
- DocType元数据和字段定义
工具
数据操作
get_documents-获取特定doctype的文档列表create_document-在ERPNext中创建新文档update_document-更新ERPNext中的现有文档delete_document-按文档类型和名称删除文档clone_document-克隆文档(可选覆盖字段)run_report-运行ERPNext报告
批量操作
bulk_create_documents-批量创建文档bulk_update_documents-批量更新文档bulk_delete_documents-批量删除文档
导出/导入
export_documents-将文档导出为JSONimport_documents-从JSON导入文档
搜索和筛选
search_documents-高级文档搜索
文档类型管理
get_doctypes-获取所有可用DocType的列表get_doctype_fields-获取特定DocType的字段列表get_doctype_meta-获取DocType的详细元数据,包括字段定义create_doctype-在ERPNext中创建具有增强字段支持的新DocTypecreate_smart_doctype-创建具有自动依赖关系解析(子表和链接验证)的新DocTypecreate_child_table-创建专门为父子关系设计的新子表DocTypeadd_child_table_to_doctype-将子表字段添加到现有DocType
智能工具(增强性能和验证)
create_smart_workflow-创建具有自动DocType验证和状态管理的新工作流create_smart_server_script-创建具有自动验证和依赖性检查的新服务器脚本create_smart_client_script-创建具有自动DocType验证和增强错误处理功能的新客户端脚本create_smart_webhook-创建具有自动验证和安全功能的新Webhookcreate_smart_report-创建具有自动DocType验证和查询优化的新报告create_smart_dashboard-创建具有自动图表和报告集成功能的新仪表板bulk_smart_create_documents-批量创建具有验证、错误处理和进度跟踪功能的文档smart_import_documents-导入具有验证、冲突解决和详细报告功能的文档
自定义应用程序创建
create_module-在ERPNext中创建新模块create_dashboard-在ERPNext中创建新仪表板create_workflow-在ERPNext中创建新工作流create_server_script-在ERPNext中创建新的服务器脚本create_client_script-在ERPNext中创建新的客户端脚本create_webhook-在ERPNext中创建新的Webhookcreate_hook-在ERPNext中创建一个新的钩子(自定义应用钩子)create_report-在ERPNext中创建新报告create_chart-在ERPNext中创建新图表create_webpage-在ERPNext中创建新网页
验证和测试
validate_doctype-验证DocType定义(基本检查)validate_workflow-验证工作流定义(基本检查)validate_script-验证脚本定义(基本检查)preview_script-预览脚本(仅语法检查)lint_script-抓取脚本(仅用于语法检查)test_script-测试脚本(仅语法检查)
版本控制和历史记录
get_document_history-获取文档的版本历史记录rollback_document-将文档回滚到以前的版本
脚手架
scaffold_app-构建一个新的自定义应用程序(返回结构)scaffold_module-构建新模块(返回结构)
UI架构生成
generate_form_schema-为DocType生成表单架构generate_dashboard_schema-为仪表板生成仪表板架构
权限和共享
get_permissions-获取DocType的权限set_permissions-设置DocType的权限smart_set_permissions-通过增强的验证和错误处理为DocType设置权限share_document-与用户共享文档
通知和自动化
create_notification-创建通知/警报create_scheduled_job-创建计划作业
文档生成
generate_doctype_docs-为DocType生成文档generate_workflow_docs-为工作流生成文档
集成
register_integration-注册新的集成服务manage_integration-更新/管理集成服务
✨ 此版本新增
- 智能工具套件:具有自动验证、依赖关系解决和详细错误报告功能的增强工具
- create_smart_workflow -使用DocType验证和状态管理创建工作流 - create_smart_server_script -创建带有验证和依赖性检查的服务器脚本 - create_smart_client_script -使用DocType验证创建客户端脚本 - create_smart_webhook -具有URL验证和安全功能的Webhook创建 - create_smart_report -使用DocType验证和查询优化创建报告 - create_smart_dashboard -使用自动图表集成创建仪表板 - bulk_smart_create_documents -批量文档创建,带有验证和进度跟踪功能 - smart_import_documents -具有冲突解决策略的文档导入
- 智能文档类型创建:子表的自动依赖关系解析和链接验证
- 增强的错误处理:详细的错误消息,为代理提供可操作的建议
- 自动权限设置:为新的DocType自动设置管理员权限(RWCD)
- 完成自定义应用程序开发:创建模块、仪表板、工作流、脚本、Webhook、报告、图表和网页
- 高级CRUD操作:完整的创建、读取、更新、删除、克隆和批量操作
- 出口/进口能力:以JSON格式导出和导入文档
- 验证和测试:验证和测试DocType、工作流和脚本
- 版本控制和历史记录:跟踪文档更改并回滚到以前的版本
- 脚手架:生成应用程序和模块结构
- UI架构生成:自动生成表单和仪表板架构
- 权限管理:获取、设置和共享文档权限
- 通知和自动化:创建通知和计划作业
- 文档生成:为DocTypes和工作流自动生成文档
- 整合管理:注册和管理外部集成
- 自动现场管理:必填字段会自动添加到DocTypes和子表中
- DocType重新加载:创建后自动重新加载DocTypes以立即应用更改
配置
服务器需要以下环境变量:
ERPNEXT_URL-ERPNext实例的基本URLERPNEXT_API_KEY(可选)-用于身份验证的API密钥ERPNEXT_API_SECRET(可选)-用于身份验证的API机密
发展
安装依赖项:
npm install构建服务器:
npm run build对于自动重建的开发:
npm run watch安装
要与Claude Desktop一起使用,请添加服务器配置:
在MacOS上: ~/Library/Application Support/Claude/claude_desktop_config.json 在Windows上: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"erpnext": {
"command": "node",
"args": ["/path/to/erpnext-server/build/index.js"],
"env": {
"ERPNEXT_URL": "http://your-erpnext-instance.com",
"ERPNEXT_API_KEY": "your-api-key",
"ERPNEXT_API_SECRET": "your-api-secret"
}
}
}
}要在VSCode中与Claude一起使用,请将服务器配置添加到:
在MacOS上: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json 在Windows上: %APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
调试
由于MCP服务器通过stdio进行通信,调试可能具有挑战性。我们建议使用 MCP检查员,可作为包脚本使用:
npm run inspector检查器将提供一个URL,用于访问浏览器中的调试工具。
使用示例
基础数据操作
获取客户列表
erpnext
get_documents
{
"doctype": "Customer"
}
创建新项目
erpnext
create_document
{
"doctype": "Item",
"data": {
"item_code": "ITEM001",
"item_name": "Test Item",
"item_group": "Products",
"stock_uom": "Nos"
}
}
更新文档
erpnext
update_document
{
"doctype": "Item",
"name": "ITEM001",
"data": {
"item_name": "Updated Item Name"
}
}
删除文档
erpnext
delete_document
{
"doctype": "Item",
"name": "ITEM001"
}
克隆文档
erpnext
clone_document
{
"doctype": "Item",
"name": "ITEM001",
"overrides": {
"item_code": "ITEM002",
"item_name": "Cloned Item"
}
}
批量操作
批量创建文档
erpnext
bulk_create_documents
{
"doctype": "Item",
"docs": [
{
"item_code": "ITEM001",
"item_name": "Item 1",
"item_group": "Products"
},
{
"item_code": "ITEM002",
"item_name": "Item 2",
"item_group": "Products"
}
]
}
批量更新文档
erpnext
bulk_update_documents
{
"doctype": "Item",
"updates": [
{
"name": "ITEM001",
"data": { "item_name": "Updated Item 1" }
},
{
"name": "ITEM002",
"data": { "item_name": "Updated Item 2" }
}
]
}
导出/导入
导出文档
erpnext
export_documents
{
"doctype": "Customer",
"filters": { "customer_type": "Company" }
}
进口单证
erpnext
import_documents
{
"doctype": "Customer",
"docs": [
{
"customer_name": "New Customer 1",
"customer_type": "Company"
},
{
"customer_name": "New Customer 2",
"customer_type": "Individual"
}
]
}
自定义应用程序创建
创建模块
erpnext
create_module
{
"module_name": "Custom App",
"app_name": "custom_app",
"custom": 1
}
创建仪表板
erpnext
create_dashboard
{
"module": "Custom",
"name": "Sales Dashboard",
"charts": [
{
"chart_name": "Monthly Sales",
"chart_type": "Bar"
}
]
}
创建工作流
erpnext
create_workflow
{
"document_type": "Sales Order",
"workflow_name": "Sales Approval Workflow",
"states": [
{ "state": "Draft" },
{ "state": "Pending Approval" },
{ "state": "Approved" }
],
"transitions": [
{
"state": "Draft",
"action": "Submit",
"next_state": "Pending Approval"
},
{
"state": "Pending Approval",
"action": "Approve",
"next_state": "Approved"
}
]
}
创建服务器脚本
erpnext
create_server_script
{
"script_type": "DocType Event",
"script": "def on_submit(doc, method):\n frappe.msgprint('Document submitted successfully')",
"reference_doctype": "Sales Order",
"name": "Sales Order Submit Script"
}
创建客户端脚本
erpnext
create_client_script
{
"script": "frappe.ui.form.on('Sales Order', {\n refresh: function(frm) {\n console.log('Form refreshed');\n }\n});",
"dt": "Sales Order",
"view": "Form",
"enabled": 1
}
创建Webhook
erpnext
create_webhook
{
"webhook_doctype": "Sales Order",
"webhook_url": "https://api.example.com/webhook",
"condition": "doc.docstatus == 1",
"request_headers": {
"Authorization": "Bearer token123"
}
}
创建报告
erpnext
create_report
{
"report_name": "Sales Summary",
"ref_doctype": "Sales Order",
"report_type": "Query Report",
"is_standard": "No",
"json": {
"query": "SELECT * FROM `tabSales Order` WHERE docstatus = 1"
}
}
创建图表
erpnext
create_chart
{
"chart_name": "Sales Trend",
"chart_type": "Line",
"document_type": "Sales Order",
"data": {
"type": "line",
"data": {
"labels": ["Jan", "Feb", "Mar"],
"datasets": [{
"label": "Sales",
"data": [1000, 1500, 2000]
}]
}
}
}
创建网页
erpnext
create_webpage
{
"title": "About Us",
"route": "about",
"content": "
About Our Company
Welcome to our company website.
",
"published": 1
}
验证和测试
验证文档类型
erpnext
validate_doctype
{
"def": {
"name": "Test DocType",
"fields": [
{
"fieldname": "test_field",
"label": "Test Field",
"fieldtype": "Data"
}
]
}
}
预览脚本
erpnext
preview_script
{
"def": {
"script": "function test() { console.log('Hello World'); }"
}
}
权限和共享
获取权限
erpnext
get_permissions
{
"doctype": "Sales Order"
}
共享文档
erpnext
share_document
{
"doctype": "Sales Order",
"name": "SO-001",
"user": "user@example.com",
"permlevel": 1
}
文档生成
生成DocType文档
erpnext
generate_doctype_docs
{
"doctype": "Sales Order"
}
脚手架
脚手架应用程序
erpnext
scaffold_app
{
"app_name": "my_custom_app"
}
脚手架模块
erpnext
scaffold_module
{
"module_name": "sales_management"
}
UI架构生成
生成表单架构
erpnext
generate_form_schema
{
"doctype": "Sales Order"
}
通知和自动化
创建通知
erpnext
create_notification
{
"notificationDef": {
"name": "Sales Order Notification",
"subject": "New Sales Order Created",
"channel": "Email",
"event": "New"
}
}
创建计划作业
erpnext
create_scheduled_job
{
"jobDef": {
"name": "Daily Sales Report",
"method": "custom_app.report.generate_daily_sales",
"frequency": "Daily"
}
}
集成
注册集成
erpnext
register_integration
{
"integrationDef": {
"name": "Payment Gateway",
"service_type": "Payment",
"api_url": "https://api.paymentgateway.com"
}
}
支持的字段类型
服务器支持所有ERPNext字段类型,包括:
- 数据 -单行文本
- 文本 -多行文本
- 选择 -下拉选择
- 链接 -引用另一个DocType
- 日期 -日期选择器
- 日期时间 -日期和时间选择器
- 货币 -货币金额
- 浮动 -十进制数
- 整数 -整数
- 检查 -复选框(0或1)
- 表格 -子表参考
- 附加 -文件附件
- 颜色 -颜色选择器
- 代码 -代码编辑器
- HTML编辑器 -富文本编辑器
- 密码 -密码字段
- 只读 -仅显示字段
错误处理
服务器包括全面的错误处理:
- ERPNext中的详细API错误消息
- 参数验证
- 身份验证检查
- 丢失数据的巧妙回退
- 创建前验证自定义对象
- 脚本语法检查
高级功能
自定义应用程序开发
此MCP服务器旨在成为定制ERPNext应用程序开发的完整引擎。你可以:
- 创建自定义模块 -组织您的自定义功能
- 构建仪表板 -使用图表和小部件可视化数据
- 设计工作流程 -自动化业务流程
- 编写脚本 -服务器端和客户端自动化
- 设置Webhooks -与外部系统集成
- 生成报告 -创建自定义数据分析
- 构建图表 -可视化数据表示
- 创建网页 -自定义web界面
- 管理权限 -控制对自定义对象的访问
- 生成文档 -自动记录您的自定义应用程序
批量操作
通过批量创建、更新和删除操作高效地处理大型数据集。
导出/导入
在ERPNext实例或环境之间备份和迁移数据。
验证和测试
在部署之前,确保您的自定义对象结构正确。
版本控制和历史记录
跟踪更改并在需要时回滚到以前的版本。
有关改进和新功能的详细信息,请参阅 改进.md.
智能文档类型创建
这 create_smart_doctype 该工具提供智能DocType创建,并自动解析依赖关系:
特性
- 自动创建子表:在主DocType之前创建子表DocTypes
- 链接验证:验证链接字段是否引用现有的DocType
- 自动权限:自动设置管理员权限(RWCD)
- 详细反馈:提供有关创建内容和任何警告的全面信息
- 错误恢复:在依赖关系失败时提出解决方案
示例:使用商品创建销售订单
erpnext
create_smart_doctype
{
"name": "Sales Order Enhanced",
"module": "Custom",
"fields": [
{
"fieldname": "customer",
"label": "Customer",
"fieldtype": "Link",
"options": "Customer",
"reqd": 1
},
{
"fieldname": "order_date",
"label": "Order Date",
"fieldtype": "Date",
"reqd": 1
},
{
"fieldname": "items",
"label": "Order Items",
"fieldtype": "Table",
"options": "Sales Order Items",
"reqd": 1
},
{
"fieldname": "delivery_address",
"label": "Delivery Address",
"fieldtype": "Link",
"options": "Address",
"reqd": 0
}
]
}
自动发生的事情:
- ✅ 如果“销售订单项”子表不存在,则创建它
- ✅ 验证是否存在“客户”和“地址”文档类型
- ✅ 设置管理员权限(读取、写入、创建、删除)
- ✅ 创建主“销售订单增强”文档类型
- ✅ 重新加载DocType以应用所有更改
错误处理
智能doctype创建提供了详细的错误信息:
- 缺少的依赖:列出需要首先创建的DocType
- 权限问题:建议检查管理员角色
- 现场验证:标识无效的字段配置
- 恢复建议:提供解决问题的具体步骤
何时使用智能创建与基本创建
- 使用
create_smart_doctype什么时候:
- 使用子表创建DocTypes - 使用链接字段引用其他文档类型 - 想要自动设置权限 - 需要详细的反馈和错误恢复
- 使用
create_doctype什么时候:
- 创建没有依赖关系的简单DocType - 希望手动控制创建过程 - 单独创建子表DocTypes
智能工具使用示例
智能工作流创建
创建具有自动验证和状态管理的工作流:
erpnext
create_smart_workflow
{
"document_type": "Sales Order",
"workflow_name": "Sales Approval Workflow",
"states": [
{
"state": "Draft",
"doc_status": "Draft",
"style": "background-color: #f0f0f0"
},
{
"state": "Pending Approval",
"doc_status": "Submitted",
"style": "background-color: #fff3cd"
},
{
"state": "Approved",
"doc_status": "Submitted",
"style": "background-color: #d4edda"
},
{
"state": "Rejected",
"doc_status": "Cancelled",
"style": "background-color: #f8d7da"
}
],
"transitions": [
{
"state": "Draft",
"action": "Submit for Approval",
"next_state": "Pending Approval"
},
{
"state": "Pending Approval",
"action": "Approve",
"next_state": "Approved"
},
{
"state": "Pending Approval",
"action": "Reject",
"next_state": "Rejected"
}
],
"send_email_alert": 1,
"is_active": 1
}
智能服务器脚本创建
创建具有自动验证功能的服务器脚本:
erpnext
create_smart_server_script
{
"script_type": "DocType Event",
"reference_doctype": "Sales Order",
"event": "after_save",
"script": "if doc.status == 'Approved':\n frappe.msgprint('Sales Order has been approved!')\n # Send notification to customer\n frappe.sendmail(\n recipients=[doc.customer_email],\n subject='Your order has been approved',\n message='Your sales order has been approved and is being processed.'\n )",
"name": "Sales Order Approval Notification"
}
智能仪表板创建
创建具有自动图表集成功能的仪表板:
erpnext
create_smart_dashboard
{
"dashboard_name": "Sales Analytics Dashboard",
"module": "Custom",
"is_default": 0,
"charts": [
{
"chart_name": "Monthly Sales Chart",
"chart_type": "Bar",
"document_type": "Sales Order",
"data": {
"type": "Bar",
"data": {
"labels": ["Jan", "Feb", "Mar", "Apr", "May", "Jun"],
"datasets": [{
"name": "Sales Amount",
"values": [10000, 15000, 12000, 18000, 20000, 25000]
}]
}
}
}
],
"cards": [
{
"card_name": "Total Sales",
"card_type": "Shortcut",
"doctype": "Sales Order"
}
]
}
智能批量文档创建
创建多个具有验证和错误处理功能的文档:
erpnext
bulk_smart_create_documents
{
"doctype": "Customer",
"docs": [
{
"customer_name": "ABC Corporation",
"customer_type": "Company",
"customer_group": "Commercial",
"territory": "United States"
},
{
"customer_name": "XYZ Industries",
"customer_type": "Company",
"customer_group": "Commercial",
"territory": "Canada"
},
{
"customer_name": "John Doe",
"customer_type": "Individual",
"customer_group": "Individual",
"territory": "United States"
}
],
"validate_before_create": 1,
"batch_size": 10,
"continue_on_error": 1,
"return_detailed_results": 1
}
智能文档导入
导入具有冲突解决功能的文档:
erpnext
smart_import_documents
{
"doctype": "Item",
"docs": [
{
"item_code": "ITEM001",
"item_name": "Product A",
"item_group": "Products",
"stock_uom": "Nos"
},
{
"item_code": "ITEM002",
"item_name": "Product B",
"item_group": "Products",
"stock_uom": "Nos"
}
],
"conflict_resolution": "skip",
"validate_before_import": 1,
"create_missing_doctypes": 0,
"preserve_creation_dates": 0,
"return_detailed_results": 1
}
智能Webhook创建
创建具有URL验证和安全功能的webhook:
erpnext
create_smart_webhook
{
"webhook_doctype": "Sales Order",
"webhook_url": "https://api.external-system.com/webhook",
"webhook_events": ["after_insert", "after_update"],
"request_structure": "JSON",
"request_headers": {
"Authorization": "Bearer your-api-key",
"Content-Type": "application/json"
},
"condition": "doc.status == 'Approved'",
"timeout": 10,
"enabled": 1
}
智能权限设置
设置具有增强验证和错误处理功能的DocType的权限:
erpnext
smart_set_permissions
{
"doctype": "MC Citizen Issue",
"perms": [
{
"role": "Administrator",
"read": 1,
"write": 1,
"create": 1,
"delete": 1
},
{
"role": "System Manager",
"read": 1,
"write": 1,
"create": 1,
"delete": 0
},
{
"role": "User",
"read": 1,
"write": 0,
"create": 0,
"delete": 0
}
],
"validate_roles": true,
"preserve_existing": true,
"reload_doctype": true
}
智能工具的好处
性能改进
- 减少了API调用:智能工具批量操作和预先验证依赖关系
- 更好的错误处理:带有可操作建议的详细错误消息
- 批处理:高效处理具有可配置批量大小的大型数据集
- 冲突解决:处理现有数据的多种策略
增强的错误处理
- 详细错误消息:清晰、描述性的错误消息,解释出了什么问题
- 情境感知建议:基于特定错误类型的智能建议
- 可行的解决方案:逐步指导解决常见问题
- 最佳实践技巧:最佳使用和配置建议
具有特定指导的错误类别
- DocType相关错误:关于缺少依赖项和创建DocType的建议
- 验证错误:现场验证指南,包括具体检查和数据类型建议
- 权限错误:管理员角色要求和功能启用指南
- 语法和代码错误:针对特定语言的语法检查和验证工具建议
- 重复和冲突错误:独特的命名建议和冲突解决策略
- URL和网络错误:Webhook URL验证和安全建议
- 批处理和性能错误:批量大小优化和处理策略建议
增强的用户体验
- 详细反馈:全面报告创建的内容、警告和错误
- 进度跟踪:长时间运行操作的实时更新
- 验证:创建前验证可防止无效数据
- 恢复建议:解决常见问题的具体步骤
何时使用智能工具
在以下情况下始终使用智能工具:
- 创建具有依赖关系的复杂资源
- 对大型数据集执行批量操作
- 处理不可信或外部数据
- 需要详细的反馈和错误报告
- 要求高性能和可靠性
- 管理数据迁移或导入
在以下情况下使用基本工具:
- 创建没有依赖关系的简单资源
- 希望手动控制创建过程
- 执行快速、一次性操作
- 使用可信、经过验证的数据
错误处理示例
智能工具提供全面的错误处理,包括详细的消息和可操作的建议:
智能文档类型创建错误
Smart DocType creation failed for 'Customer_Order':
DocType 'Supplier' referenced in Link field does not exist
💡 Suggestions:
- Use create_smart_doctype tool for automatic dependency resolution
- Ensure Link fields reference existing DocTypes
- Create child table DocTypes before referencing them in Table fields智能工作流创建错误
Smart Workflow creation failed for 'Order_Approval':
State 'Pending' referenced in transition does not exist in states array
💡 Suggestions:
- Ensure all states referenced in transitions exist in the states array
- Check that state names match exactly (case-sensitive)
- Verify transition rules are valid智能服务器脚本创建错误
Smart Server Script creation failed for 'Order_Validation':
Invalid Python syntax in script
💡 Suggestions:
- Check Python syntax in your script
- Ensure all imports are valid
- Verify variable names and function calls
- Use the lint_script tool to validate syntax智能Webhook创建错误
Smart Webhook creation failed for 'https://api.example.com/webhook':
Invalid webhook URL format
💡 Suggestions:
- Ensure the webhook URL is valid and accessible
- Check that the URL uses HTTPS for security
- Verify the endpoint accepts POST requests
- Test the URL manually to ensure it responds批量智能创建错误
Bulk Smart Create failed for DocType 'Customer':
Required field 'customer_name' is missing in document 3
💡 Suggestions:
- Ensure all required fields are provided
- Check that field names match the DocType schema
- Verify field data types are correct
- Use get_doctype_meta to check field definitions