AI导哈

ERP集成HTTP服务器

Xentral MCP HTTP服务器是一个用于Xentral ERP集成的模型上下文协议（MCP）HTTP服务器，它暴露了完整的Xentral API，并为日常ERP工作流程提供了便捷工具。

  • by matthiashuebner
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 matthiashuebner/xentral-mcp

使用说明

Xentral MCP HTTP服务器

用于Xentral ERP集成的模型上下文协议（MCP）HTTP服务器 暴露 完整的Xentral API --官方的每一个端点 Xentral OpenAPI规范 --作为MCP工具，以及为日常ERP工作流程精心策划的便利工具。

🚀 特性

  • API全面覆盖339个工具，涵盖所有记录在案的工具 Xentral API端点（客户、产品、销售订单、发票、， 仓储、会计、分析、POS、生产等）
  • 精心策划的工具：手写便利工具，表格格式 输出(search_customers, search_products)--它们覆盖生成的 名称冲突工具
  • 真正的MCP HTTP服务器：完全兼容JSON-RPC 2.0的MCP实现
  • Xentral原生过滤：deepObject查询序列化 (filter[0][key]=name&filter[0][op]=equals&filter[0][value]=Miller), 分页(page[number], page[size])和排序(order[0][field])
  • 二进制下载：保存PDF/CSV/ZIP响应（例如发票PDF） 到 downloads/ 而不是淹没上下文窗口
  • 响应截断：大列表响应会被修剪，并提示 使用过滤器/分页
  • 默认情况下已通过身份验证：每个端点上的承载令牌身份验证；绑定到 仅限环回，拒绝在没有令牌的情况下将自己暴露在网络中
  • SSRF硬化：API基本URL已验证（HTTPS，主机允许列表， 内部/元数据地址被阻止），然后再发送任何请求
  • 运行时配置：在不重新启动的情况下动态更新API凭据
  • 修改日志记录：请求方法、工具名称和参数 钥匙 是 记录——从不隐藏值或PII

📋 需求

🛠️ 安装

git clone https://github.com/matthiashuebner/xentral-mcp.git
cd xentral-mcp
pip install -r requirements.txt
cp .env.example .env
# Edit .env: set XENTRAL_API_URL (instance base URL, no /api suffix),
# XENTRAL_API_KEY (personal access token), and MCP_AUTH_TOKEN

生成身份验证令牌：

python -c "import secrets; print(secrets.token_urlsafe(32))"

🔒 安全模型

  • 默认情况下为环回。 MCP_SERVER_HOST 默认为 127.0.0.1The 服务器 拒绝开始 在任何其他界面上，除非 MCP_AUTH_TOKEN 已设置--在没有令牌的情况下永远不要暴露它。
  • 令牌身份验证。 每个端点，除了 /health 需要 Authorization: Bearer <MCP_AUTH_TOKEN>。如果未配置令牌，则访问 仅在环回时被容忍（带有启动警告）。
  • 没有CORS。 跨源访问已禁用，因此网站无法驱动 API。
  • SSRF防护装置。 XENTRAL_API_URL 必须是HTTPS（本地主机除外）并且必须 不解析为私有/环回/链路本地/元数据地址。集 XENTRAL_ALLOWED_HOSTS 以固定允许的主机。
  • 没有调试服务器。 Werkzeug交互式调试器从未启用。

🏃 运行服务器

本地开发（环回、开发服务器）：

python mcp_server.py

生产环境——在TLS终止和身份验证后使用真正的WSGI服务器 反向代理。 不要 直接公开Flask开发服务器：

gunicorn --bind 127.0.0.1:8888 wsgi:app

服务器注册了341个工具。经过身份验证的呼叫携带承载令牌：

curl -H "Authorization: Bearer $MCP_AUTH_TOKEN" http://localhost:8888/info

🔧 工具目录（自动生成的API工具）

所有API工具都是从官方的OpenAPI规范编译成 xentral/openapi/catalog.json （承诺回购）。当Xentral 发布API更改，使用以下方法重新生成：

python scripts/generate_catalog.py            # downloads the latest spec
python scripts/generate_catalog.py --spec my-spec.json   # or use a local file

工具名称遵循规范的操作ID： customer.list.v2 → customer_list_v2, salesOrder.actions.cancel → sales_order_actions_cancel. 看 mcp-tools-list.md 对于按以下方式分组的完整列表 资源。

工具参数

  • 路径参数 （例如。 id)是顶级参数
  • filter：数组 {key, op, value} 对象--允许的键/运算符 嵌入在每个工具的模式中
  • page: {"number": "1", "size": "20"}
  • order：数组 {field, dir} 物体(dir: asc/desc)
  • body：用于创建/更新操作的JSON请求体（包括模式）
  • content_type：用于特殊行为的可选供应商内容类型 （例如。 application/vnd.xentral.upsert+json 上 product_create)

🔍 测试

除以下端点外的所有端点 /health 在以下情况下需要持票人令牌 MCP_AUTH_TOKEN 已设置。

# Health check (public)
curl http://localhost:8888/health

# List all tools
curl -X POST http://localhost:8888/mcp \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Call a tool: list customers named Miller
curl -X POST http://localhost:8888/mcp \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"customer_list_v2","arguments":{"filter":[{"key":"name","op":"equals","value":"Miller"}],"page":{"number":"1","size":"10"}}}}'

📁 项目结构

  • mcp_server.py -主Flask HTTP服务器和工具发现
  • mcp_protocol.py -MCP JSON-RPC协议的实现
  • config.py -配置管理
  • scripts/generate_catalog.py -将OpenAPI规范编译到工具目录中
  • xentral/openapi/ -生成的工具目录+通用API执行器
    • catalog.json -编译的工具定义（339个端点）
    • executor.py -通用HTTP执行器（路径、deepObject查询、主体）
    • loader.py -从目录构建MCP工具
  • xentral/*.py -手写便利工具（自动发现）
  • mcp_client.py -CLI测试客户端
  • mcp-tools-list.md -生成所有工具的概述
  • .env.example -配置模板

🌐 HTTP端点

  • POST /mcp -主MCP JSON-RPC端点（初始化、工具/列表、工具/调用）
  • GET /health -健康检查
  • GET /info -服务器信息
  • GET /tools -列出所有工具（纯JSON）
  • POST /config/credentials -运行时更新API凭据

📞 支持

有关问题，请检查登录 mcp_server.log.Xentral返回的API错误 （包括验证细节）传递给MCP客户端。

ERP自动化快乐！ 🚀

相关 MCP