sanxiao-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@sanxiao-mcp list my recent reimbursements"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
sanxiao-mcp — Kingdee Cloud·Xingchen "Sanxiao Project Management" MCP Server
GC032 Financial Agent · Sanxiao endpoint. App identifier bdi_projectmanagement,
subscription URL https://cloud.kingdee.com/kae/#/market/detail?sid=1285.
Implemented per the official 《Sanxiao Project Management API_2025》 documentation + 《Kingdee Sanxiao Project Management API Development Framework》. Phase 1 read-only: all query operations enabled; write operations are in place in code but rejected by guards by default.
The shape of the Sanxiao API (understand this first, the rest is easy)
Sanxiao is not "one endpoint per business" — it is generic Bill CRUD:
all bills — project profiles, loans, reimbursements, payments, working-hour entries, purchase requests — go through the same set of interfaces,
driven by formId + field identifiers.
POST https://bj1-api.kingdee.com/bdiprojectapi/common/{action}
后端 openapi/ierp/kapi/app/bdi_projectmanagement/{action}
action ∈ { listQuery, getById, saveOrUpdate, submit, unSubmit,
audit, unAudit, delete, push, operation }So this service's structure is also "one gateway + two layers of wrapping", rather than dozens of endpoint constants.
Related MCP server: iGuat-MCP
Table of Contents
sanxiao/
├── config.py 环境与鉴权四要素;url() / headers() 在这里定形
├── forms.py formId 登记表 + 中文别名解析(项目档案 → bdi_projectfile)
├── query.py qParams 结构化查询 DSL:构造、校验、还原成类 SQL 可读串
├── models.py saveOrUpdate 字段模型(8 种 fType + 分录 + 下推 + 附件)
├── guards.py 白名单 + 默认拒绝 + 审计
├── client.py 唯一 HTTP 出口 _post(),读写方法都从这里过
└── server.py 28 个 MCP 工具(通用层 + 语义层)
test_connection.py L1 配置 → L2 网络 → L3 鉴权 → L4 只读 → L5 守卫
tests/ pytest:query / models / guards / clientAuthentication: four request headers, no signature
Unlike kingdee-star-mcp (jdy open gateway) — Sanxiao requires no HMAC signature,
just four headers, all obtained in advance via the standard Xingchen API:
Header | Source of value |
| Product account-set-level token, obtained via Xingchen standard API authentication |
| IDC domain = the |
| Authorization info, pushed by the open platform to the sandbox message receiving address |
| Same as above |
Pitfall warning: The official docs explicitly state "when debugging in the cloud platform API marketplace,
X-GW-Router-Addrcan be ignored". So many people get it working in the marketplace, then hit 404 as soon as they write code — because code calls must include this header.config.headers()already handles this; don't delete it.
Once you have the four elements, fill them into .env (template in .env.example).
Quick Start
pip install -r requirements.txt
cp .env.example .env # 填入四要素
pytest -q # 69 项单测应全绿
python test_connection.py # 分层联调,结果写入 connection_test_result.txtOn Windows, just double-click run_test.bat.
MCP Tools (28)
Meta Information
Tool | Purpose |
| Gateway address, read-only switch, readiness status of the four elements and what's missing |
| Registered formIds, Chinese names, default fields |
| Available actions, read-only operation whitelist, currently permitted write actions |
Generic Layer — Full Mapping of Official Interfaces
Tool | Official Interface |
|
|
|
|
|
|
| Local tool: translates simplified conditions into |
Semantic Layer — No Need to Memorize formIds
sx_list_projects / sx_list_reimbursements / sx_list_loans /
sx_list_payments / sx_list_working_hours / sx_get_bill
sx_query_cost_budget / sx_query_material_budget / sx_query_working_hour_budget
sx_get_user_permission / sx_get_form_config / sx_workflow_status / sx_get_app_parameter
Write Layer — Rejected by Default
sx_build_bill_payload (only assembles, does not send; usable in phase 1 for manual review of the payload)
sx_save_or_update / sx_submit / sx_un_submit / sx_audit / sx_un_audit
/ sx_delete / sx_push
How to Write Query Conditions
The official qParams is an array of conditions: top-level items are joined by and, and within a condition group items are joined by joinKey.
[
{ "childGroup": false, "qKey": "number", "qCp": "like", "qValue": "ew" },
{ "childGroup": true, "joinKey": "or", "childCondition": [
{ "childGroup": false, "qKey": "number", "qCp": "=", "qValue": "new5" },
{ "childGroup": false, "qKey": "number", "qCp": "=", "qValue": "New" }
]}
]
// 等价于 number like '%ew%' and (number='new5' or number='New')Comparison operators: = > >= < <= != like likeLeft. There is no in — use query.any_of()
or the or-group in sx_build_query to simulate it. Entry fields are written as "entry identifier.field identifier",
e.g. projectfileteam.teamstaff.
Security Model
The guard is a whitelist + default-deny three-layer design:
Action classification —
listQuery/getById/operationare reads; the other seven are writes.operationKey whitelist —
operationlooks like a read interface, butoperationKeyis a free-form string, so the nine methods in doc sections 10.1–10.9 get a second whitelist pass.Funds-related operations permanently write-blocked — writes and workflow actions on payment bills (
bdi_ex_pay*), evenSX_ALLOW_WRITE_ACTIONS=*will not bypass this.
Order for enabling writes in phase 2: SX_READONLY=false → add actions one by one in SX_ALLOW_WRITE_ACTIONS
for gray rollout. Do not jump straight to *.
All calls and blocks are logged to the sanxiao.audit logger.
Real Payloads Overturn What the Docs Suggest
The official 《Sanxiao-API Reference Code》 is a complete bdi_projectfile bill payload
(saved as tests/fixtures/projectfile_reference.json). It is more trustworthy than the doc examples,
and overturns four assumptions taken for granted — each one is pinned down in tests/test_reference_payload.py,
and reverting any of them will fail immediately:
What the doc examples suggest | What the real payload shows |
Every field has | Empty-value fields omit the |
|
|
| Native |
|
|
The third one is the most dangerous: an earlier str(d["fValue"]) in field_from_dict,
when hitting {"fType":"enum","fValue":true}, would produce Python-style "True" —
a string with a capital T, which the server does not recognize, and the error message will not tell you this is the cause.
Now fValue is passed through as-is.
The benefit is that getById responses can be fed straight back into saveOrUpdate (change one or two fields and save again),
lossless round-trip, and this path is guarded by test_roundtrip_is_lossless.
Additionally, eight base-data formIds were extracted from the bd field of the payload and registered in forms.py:
bd_employee, bd_department, bd_customer, bdi_bd_customer_fork,
bdi_projecttypes, bdi_projectarea, bdi_projectstauts, bdi_projectroles.
bdi_projectstautsis not a typo — the vendor spelled status as stauts, and both the formId and field names use that spelling. Don't "fix it" out of habit.
Where Field Identifiers Come From
Don't guess. The authoritative method is in the Xingchen UI: Bill list → More → Import Data → Template Management → New Template.
Once running, you can also look it up in reverse: sx_get_form_config(form_id) calls
operation.getUserconfig and returns that bill's field configuration.
forms.py registers 15 formIds: seven from the official docs
(bdi_projectfile, bdi_ex_loan, bdi_ex_bx, bdi_ex_pay,
bdi_fillinworkinghours, pur_bill_request, bd_auxinfo),
and eight base-data references from the reference-code payload. For other bills, just pass the formId
directly to sx_list_query — no need to register first.
Same for field names — only bdi_projectfile's fields have been verified against the real payload
(note it uses status/enable, not billstatus; that belongs to business bills).
The default fields for other bills are still inferred by convention; after getting them working, please verify with sx_get_form_config.
Relationship with kingdee-star-mcp
The two are two open capabilities of the same Xingchen account set, each deployed independently:
kingdee-star-mcp | sanxiao-mcp | |
Gateway |
|
|
Auth | HMAC signature + app-token two-layer credentials | Four headers, no signature |
Endpoints |
|
|
Coverage | Finance (vouchers, reimbursements, receivables/payables) | Project management (projects, working hours, budgets, reimbursements) |
Sanxiao's Token must first be obtained via the Xingchen standard API — if you've already
gotten the authorization chain working in kingdee-star-mcp, you can fill the token you obtained
along with the domain/groupname/accountid from the authorization push directly into this project's .env.
Known Gaps
The official docs do not provide a unified response body schema;
client._unwrap()does a loose unwrap: if it can recognizeerrcode/success/datait normalizes, otherwise it returns as-is — better to return extra data than to swallow data by guessing the structure wrong. It can be tightened once real responses are available.Bill status codes are not fully documented. In the reference code, project profile
status="A",enable="1", but what A/B/C each mean, and the value domain ofbillstatusfor business bills, still lack authoritative explanation. The semantic layer'sstatusparameter currently passes through the raw identifier.In the reference code, a few fields have contradictory
fTypevalues —phaseplanenddate,phaseenddateare declared asnumyet are clearly dates. This is an inconsistency in the vendor's own payload; the model layer accepts it as-is without correction, so as not to "help in the wrong direction".Attachment upload goes through base64; large files need evaluation against the gateway size limit, which the docs do not specify.
Available Tools
28 toolssx_auditC
审核单据(官方 audit)。默认被只读守卫拒绝。
Inputs: data_id (required), form_id (required).
sx_build_bill_payloadA
【只组装不发送】把单据 dict 校验并序列化成官方 dataJsonStr,供人工核对。
bill 形如: {"billFormId":"bdi_fillinworkinghours","billId":"0","billNo":"", "fields":[{"fType":"text","fKey":"billno","fValue":"..."}, {"fType":"bd","fFormId":"bdi_projectfile","fKey":"projectfiles","fValue":"..."}, {"fType":"entry","fKey":"entryworkinghours", "fEntities":[{"entryId":"0","entryFields":[...]}]}]} 本工具不调用任何接口,只读环境下也可放心使用。
Inputs: bill (required).
sx_build_queryA
把简化条件翻译成官方 qParams 数组,不发起请求,用于先验证再查询。
conditions 每项形如 {"key": "billdate", "op": ">=", "value": "2025-01-01"}; 或分组 {"join": "or", "children": [ ...同上... ]}。 返回 qParams 数组与类 SQL 的可读描述。
Inputs: conditions (required).
sx_capabilitiesA
列出可用的 action、只读 operation 方法白名单,以及当前放行的写动作。
Inputs: no named parameters.
sx_deleteB
删除单据(官方 delete)。默认被只读守卫拒绝。
Inputs: data_id (required), form_id (required).
sx_get_app_parameterC
获取三效系统参数(operation.loadAppParameter)。
Inputs: para_code (required), app_code.
sx_get_billB
查任意单据详情,form_id 支持中文别名。with_attachments=True 时带上默认附件面板。
Inputs: data_id (required), form_id (required), with_attachments.
sx_get_by_idC
按单据 Id 查详情(官方 getById)。attach_keys 为附件面板标识,如 ["attachmentpanel"]。
Inputs: data_id (required), form_id (required), attach_keys.
sx_get_form_configC
查询单据字段配置(operation.getUserconfig)——想知道某单据有哪些字段标识时用这个。
Inputs: form_id (required), form_id_ex, entry_marks.
sx_get_user_permissionC
查询当前用户对若干单据的权限(operation.getUserPermission)。
Inputs: form_ids (required).
sx_healthB
健康检查:返回网关地址、只读开关、鉴权四要素就绪状态与缺失项。
Inputs: no named parameters.
sx_list_formsA
列出本服务已登记的三效单据标识(formId)、中文名与默认查询字段。
未登记的单据仍可直接把 formId 传给 sx_list_query,此表只是便利。 formId 与字段标识的权威来源:星辰单据列表 → 更多 → 引入数据 → 模板管理 → 新增模板。
Inputs: no named parameters.
sx_list_loansC
查询借款单(bdi_ex_loan)。
Inputs: fields, status, bill_no, date_to, +4 more.
sx_list_paymentsB
查询付款单(bdi_ex_pay)。只读——付款类写操作在本服务中永久禁止。
Inputs: fields, status, bill_no, date_to, +4 more.
sx_list_projectsC
查询项目档案(bdi_projectfile)。keyword 对项目名称做 like 模糊匹配。
Inputs: fields, keyword, order_by, page_size, +1 more.
sx_list_queryA
列表查询任意三效单据(官方 listQuery)。
form_id: 单据标识或中文别名,如 bdi_projectfile / "项目档案" fields: 字段标识,逗号分隔;分录字段写「分录标识.字段标识」, 如 "id,number,name,projectfileteam.teamstaff";留空取默认字段 params: qParams 条件数组,叶子形如 {"childGroup": false, "qKey": "number", "qCp": "like", "qValue": "ew"} 条件组形如 {"childGroup": true, "joinKey": "or", "childCondition": [ ...叶子... ]} 顶层各项之间是 and。比较符:=,>,>=,<,<=,!=,like,likeLeft order_by: 如 "id desc,name asc" data_permission: all 全部 / self 仅制单人自己
Inputs: form_id (required), fields, params, order_by, +3 more.
sx_list_reimbursementsB
查询报销单(bdi_ex_bx)。日期形如 2025-01-01;status 为单据状态标识,如 A 暂存。
Inputs: fields, status, bill_no, date_to, +4 more.
sx_list_working_hoursC
查询工时填报(bdi_fillinworkinghours)。分录标识 entryworkinghours。
Inputs: fields, status, bill_no, date_to, +4 more.
sx_operationB
执行三效自定义方法(官方 operation)。
只读白名单:loadAppParameter, getUserPermission, getUserconfig, materialBudget, costBudget, workingHourBudget, getAttachFieldPermission, enableWorkflow, isInWorkflow。参数用 dict 传,本工具负责序列化成 官方要求的 operationParJsonStr 字符串。
Inputs: operation_key (required), par.
sx_pushA
单据下推(官方 push),如借款单下推报销单。
按单据下推传 bill_ids;按分录下推传 entry_ids + src_entry_mark(源单分录标识)。 返回的目标单据数据包在保存时需回传 pushPar。默认被只读守卫拒绝。
Inputs: src_form_id (required), dest_form_id (required), bill_ids, entry_ids, +1 more.
sx_query_cost_budgetB
查询费用预算(operation.costBudget)。now_bill_id 新建单据传 0。
Inputs: form_id (required), project_id (required), cost_id, now_bill_id, +2 more.
sx_query_material_budgetC
查询物料预算(operation.materialBudget)。
Inputs: form_id (required), project_id (required), material_id, now_bill_id, +1 more.
sx_query_working_hour_budgetC
查询工时预算(operation.workingHourBudget)。
Inputs: form_id (required), project_id (required), now_bill_id.
sx_save_or_updateB
保存/修改单据(官方 saveOrUpdate)。默认被只读守卫拒绝,需 SX_READONLY=false 且 SX_ALLOW_WRITE_ACTIONS 含 saveOrUpdate 才会真正发送。
Inputs: bill (required).
sx_submitC
提交单据审批(官方 submit)。默认被只读守卫拒绝。
Inputs: data_id (required), form_id (required).
sx_un_auditC
反审核单据(官方 unAudit)。默认被只读守卫拒绝。
Inputs: data_id (required), form_id (required).
sx_un_submitC
撤销提交(官方 unSubmit)。默认被只读守卫拒绝。
Inputs: data_id (required), form_id (required).
sx_workflow_statusC
查工作流状态:是否启用工作流;给了 bill_id 时再查该单是否已在流程中。
Inputs: form_id (required), bill_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
Most tools target distinct resources or actions, e.g. list_query is generic while list_projects is form-specific. However, sx_get_by_id and sx_get_bill both retrieve single bills with similar semantics, and sx_operation overlaps with specific query tools, creating minor ambiguity.
All tools share the sx_ prefix, and most follow verb_noun patterns (sx_list_*, sx_get_*, sx_query_*, sx_build_*). However, sx_health and sx_capabilities are nouns rather than verbs, and there is mixing between list/get/query verbs with no strict rule, slightly reducing predictability.
With 28 tools, the server clearly exceeds the 25-tool threshold for heavy sets. While many tools target specific query types, generic tools like sx_list_query could absorb some of them, making the surface feel redundant and bloated.
The toolset covers the full lifecycle of bills: list, get, save/update, delete, audit, submit, unsubmit, unaudit, and push. It also includes capabilities like budget queries, permissions, form config, and health checks. Only minor gaps exist, such as batch operations or specialized export tools, but core workflows are well-supported.
Maintenance
Related MCP Connectors
Manage Timequip projects, tasks, comments, members, and dashboards through MCP.
One governed MCP endpoint for 40+ business systems. Read-only, source-cited answers.
A paid remote MCP for AI SDK data query MCP, built to return verdicts, receipts, usage logs, and aud
MCP server for Arcoro and ExakTime — workforce data, jobs, cost codes and locations.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables read-only access to Kingdee Cloud Star financial data, invoice tax calculation, and generation of reimbursement draft payloads through MCP tools.17-
- FlicenseNot gradedqualityDmaintenanceEnables read-only queries of i桂航 campus data, including schedules, classes, terms, and campus information through MCP tools.-
- AlicenseNot gradedqualityBmaintenanceProvides MCP access to an internal performance and consulting project collaboration system, enabling management of projects, stages, tasks, materials, evidence, approvals, and experience in a traceable chain, with Feishu for organization sync and collaboration.Apache 2.0
- FlicenseNot gradedqualityAmaintenanceEnables Claude, Cursor, and other AI assistants to query and operate Kingdee Cloud Star ERP—covering purchasing, sales, inventory, manufacturing, costing, fixed assets, financial reports, and approvals—using natural language through 87 MCP tools.-