kingdee_star
kingdee_star —— 金蝶云星辰 MCP Server
GC032 财务智能体 · 金蝶端(钉钉侧已由钉钉 MCP 打通,本仓库只做金蝶)。 对齐需求 v2.1:一期只读 + 发票税额计算 + 报销单待录入报文生成。
v0.2.0 重要变更:鉴权、端点、税额引擎均已按官方文档与沙箱实测重写。 v0.1.0 的端点常量(
/finance/expense一类)在真实网关上并不存在,请勿沿用。
目录
kingdee_star/
├── kingdee_star/
│ ├── config.py # 环境/凭据(两层:ISV + 租户),只读/写开关
│ ├── signer.py # jdy 网关签名(X-Api-Signature / app_signature)
│ ├── models.py # Invoice / ExpenseDraft / ExpenseLine
│ ├── tax_engine.py # 发票税额决策树(专票/铁路/航空/旅客运输/公路水路/其他)
│ ├── guards.py # 只读守卫 + 受控写入守卫(白名单+默认拒绝)+ 审计
│ └── star_client.py # 鉴权 + 只读查询 + 报销报文生成
├── test_connection.py # 分层联调测试(配置→网络→鉴权→只读→dry-run)
├── run_test.bat # Windows 一键跑:装依赖 + 单测 + 联调
├── tests/ # pytest:税额引擎 + 签名算法
└── .env.example # 配置模板Related MCP server: Kingdee MCP Server
鉴权(两层凭据,别搞混)
层 | 取值 | 用途 |
ISV 应用 |
|
|
租户账套 |
| 计算 |
链路:
POST /jdyconnector/app_management/push_app_authorize?outerInstanceId=...
→ data[0].appKey / appSecret
GET /jdyconnector/app_management/kingdee_auth_token?app_key=..&app_signature=..
→ data['app-token'](有效期约 2h)
GET /jdy/v2/{module}/{object}
→ 头带 app-token + X-Api-* 签名 + X-GW-Router-Addr三个容易踩的坑(signer.py 已处理,改动前先看注释):
hash_hmac(..., raw_output=false)返回 hex 字符串,base64 的输入是这个 hex,不是 raw digest。待签名串里的头名是小写,且 nonce 在前、timestamp 在后,与
X-Api-SignHeaders声明的顺序相反;末尾还有一个换行。X-GW-Router-Addr(取推送报文里的domain,如https://tf.jdy.com)是全局必填头,官方文档 370 个接口全部标注必填。
快速开始
pip install -r requirements.txt
cp .env.example .env # 填入凭据
pytest -q # 单测应全绿
python test_connection.py # 联调:配置→网络→鉴权→只读→dry-runWindows 直接双击 run_test.bat(结果写入 connection_test_result.txt)。
作为 MCP Server 使用
python -m kingdee_star.server # stdio把 mcp.config.json 里的 kingdee-star 合并进客户端 mcpServers 配置(改 cwd 与 env)。
兼容 mcp 1.x 与 2.x 两个大版本。
工具清单(17)
类别 | 工具 | 端点 |
元/鉴权 |
| — |
探针 |
|
|
只读·科目 |
|
|
只读·凭证 |
|
|
只读·发票 |
|
|
只读·收付 |
|
|
只读·往来 |
|
|
只读·报销 |
|
|
计算 |
| 本地,不调金蝶 |
报文生成 |
| 仅 dry-run,见下 |
销项/进项发票不是两个端点,用
fi/invoice_fp的bill_type/invoice_type过滤。
⚠ 报销写入的现实约束
官方开放平台共 370 个接口,ebx 模块只有「报销单详情」一个 GET,
既没有报销单列表,也没有任何报销单保存接口。
因此需求 v2.1 里的「发票代填报销单草稿」无法通过开放 API 落库:
kdy_fill_reimbursement只产出已算好税额、已过合规校验的待录入报文,dry_run=False会被显式拒绝。要真正自动写入,只能走非开放-API 通道(RPA / 前端接口 / 找金蝶开定制接口)。
安全边界
JDY_READONLY=true→ 纯只读。守卫层为白名单 + 默认拒绝:路径变形(尾斜杠、子路径、大小写)均无法绕过。
付款/凭证/科目写入、报销提交审批 → 永久禁止(
FORBID_ENDPOINTS),人工执行。全量审计:
kingdee_star.audit日志。
税额引擎
票种 | 口径 |
专票 | 取票面税额与不含税金额 |
旅客运输(列示税额) | 取票面税额;缺 |
铁路 | ÷1.09×9% |
航空 | (票价+燃油附加费)÷1.09×9%,校验用 |
公路/水路 | ÷1.03×3% |
其他普票 | 不可抵扣;若票面已列税额会抛提示要求人工确认票种 |
旅客运输抵扣缺出行人 → 合规校验置为不可抵扣。负数(红字)发票直接拒绝。
Available Tools
17 toolskdy_auth_fetch_tokenC
换取 app-token。缺 app_key/app_secret 时自动先用第三方实例ID走 push_app_authorize。
Inputs: uid.
kdy_calc_invoice_taxC
发票税额计算(本地税额引擎,不调用金蝶)。 返回 税额/不含税/是否可抵扣/说明/合规问题。票种 kind 可空(自动推断)。
Inputs: total (required), invoice_no (required), fuel, kind, +5 more.
kdy_current_userA
当前用户信息(只读,零参数,最轻量的连通性探针)。GET /jdy/v2/sys/current_user_info。
Inputs: no named parameters.
kdy_customer_debtC
查询客户欠款余额(只读)。GET /jdy/v2/arap/customer_debt。
Inputs: customer_id.
kdy_fill_reimbursementA
发票代填报销单草稿(受控写入)。 invoices: [{invoice_no,total,category_hint?,kind?,title?,face_tax?,face_net?,passenger?,fuel?}, ...] 默认 dry_run=True(只构造并过守卫,不真正提交);付款/提交审批仍人工。
Inputs: invoices (required), applicant (required), trip_form_id (required), dry_run, +1 more.
kdy_get_invoiceA
按 id 查询发票详情(只读)。GET /jdy/v2/fi/invoice_detail。
Inputs: invoice_id (required).
kdy_get_reimb_detailA
查询报销单详情(只读)。GET /jdy/v2/ebx/reimb_detail。 reimb_id 为单据内码;number 为单据编号(按沙箱实测择一传入)。
Inputs: number, reimb_id.
kdy_get_voucherA
按 id 查询凭证详情(只读)。GET /jdy/v2/fi/voucher_detail。
Inputs: voucher_id (required).
kdy_healthB
健康检查:返回环境、基址、只读开关、凭据与令牌就绪状态。
Inputs: no named parameters.
kdy_list_accountC
查询会计科目列表(只读,对账基准)。GET /jdy/v2/fi/account。
Inputs: page, size.
kdy_list_account_typeA
查询科目类别(只读,零参数)。GET /jdy/v2/fi/account_type。
Inputs: no named parameters.
kdy_list_ap_payA
查询付款单列表(只读,付款核对;付款写入永久禁止)。GET /jdy/v2/arap/ap_credit。
Inputs: page, size.
kdy_list_ar_receiveB
查询收款单列表(只读)。GET /jdy/v2/arap/ar_credit。
Inputs: page, size.
kdy_list_expenseB
查询报销单列表(只读)。注意:ebx 列表端点尚未经沙箱确认,可能返回 404。
Inputs: page, size.
kdy_list_invoiceB
查询发票列表(只读)。GET /jdy/v2/fi/invoice_fp。 销项/进项不是不同端点,用 bill_type / invoice_type 过滤。
Inputs: page, size, end_date, bill_type, +2 more.
kdy_list_voucherC
查询会计凭证列表(只读,进销项/账面对账)。GET /jdy/v2/fi/voucher。
Inputs: page, size, end_date, start_date.
kdy_reconciliationC
查询往来对账单(只读)。GET /jdy/v2/arap/reconciliation_statement。
Inputs: end, start, customer_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
每个工具针对明确的资源或操作:健康检查、令牌获取、用户、科目、凭证、发票、收付款、对账、余额、报销、税务计算和填写。list_与get_工具清晰区分实体层级,没有两个工具做同一件事。
大多数工具采用 'kdy_动词_名词' 模式,如 list_account, get_voucher, calc_invoice_tax。少数如 reconciliation 和 customer_debt 省略动词,但仍是可读的名称,整体风格基本统一,仅有轻微不一致。
17个工具对于财务查询域来说略多,但每个工具覆盖了必要的实体和操作,没有冗余。这个数量在合理范围内,略超出典型的最优区间但完全可接受。
覆盖了核心财务实体(科目、凭证、发票、收付款、对账、客户欠款、报销)的查询和详情,并提供了税务计算和受控写入凭证代填。缺少更新删除操作,但该API设计为只读为主,写入受控,基本满足需求。
Related MCP Connectors
Discover, plan and run tools across your connected business systems through one OAuth MCP endpoint
Read PaySpace employees, organization, payroll runs, payslips and leave records. Read-only.
Read-only, permission-scoped PIO team workflows for payments, payroll and employee onboarding.
Secure remote MCP for supported accounting workflows in authorized KROS companies.
Related MCP Servers
- FlicenseCqualityDmaintenanceEnables read-only querying of Kingdee's Three-Effect project management system, covering projects, reimbursements, loans, payments, working hours, and budgets, via MCP tools.28-
- 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.-
- FlicenseNot gradedqualityAmaintenanceEnables Claude, Cursor, and other AI assistants to query and operate Kingdee Cloud Star ERP in natural language through MCP tools. It supports purchasing, sales, inventory, finance, production, costs, assets, auditing, workflow, and metadata operations.-
- FlicenseNot gradedqualityAmaintenanceEnables AI assistants such as Claude, Cursor, and Windsurf to query and operate Kingdee Cloud Star ERP in natural language, covering procurement, sales, inventory, finance, production, cost, assets, and approval workflows through MCP tools.-