kingdee_star
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., "@kingdee_star Calculate the tax deduction for my train ticket"
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.
kingdee_star — Kingdee Cloud Star MCP Server
GC032 Financial Agent · Kingdee side (the DingTalk side is already connected via DingTalk MCP; this repo only handles Kingdee). Aligned with requirement v2.1: Phase 1 read-only + invoice tax calculation + reimbursement form pending-entry message generation.
v0.2.0 Important changes: Authentication, endpoints, and the tax engine have all been rewritten per the official docs and sandbox testing. The endpoint constants from v0.1.0 (like
/finance/expense) do not exist on the real gateway; do not reuse them.
Table of Contents
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
Authentication (two layers of credentials, don't mix them up)
Layer | Value | Purpose |
ISV app |
|
|
Tenant account set |
| Compute |
Flow:
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-AddrThree easy pitfalls (already handled in signer.py; read the comments before changing anything):
hash_hmac(..., raw_output=false)returns a hex string; the base64 input is this hex, not the raw digest.Header names in the string to sign are lowercase, and nonce comes first, timestamp last — the reverse of the order declared in
X-Api-SignHeaders; there is also a trailing newline.X-GW-Router-Addr(taken from thedomainin the push message, e.g.https://tf.jdy.com) is a globally required header; all 370 endpoints in the official docs mark it as required.
Quick Start
pip install -r requirements.txt
cp .env.example .env # 填入凭据
pytest -q # 单测应全绿
python test_connection.py # 联调:配置→网络→鉴权→只读→dry-runOn Windows, just double-click run_test.bat (results are written to connection_test_result.txt).
Using as an MCP Server
python -m kingdee_star.server # stdioMerge kingdee-star from mcp.config.json into the client's mcpServers config (adjust cwd and env).
Compatible with both mcp 1.x and 2.x major versions.
Tool List (17)
Category | Tools | Endpoint |
Meta/Auth |
| — |
Probe |
|
|
Read-only · Accounts |
|
|
Read-only · Vouchers |
|
|
Read-only · Invoices |
|
|
Read-only · Receipts/Payments |
|
|
Read-only · Transactions |
|
|
Read-only · Reimbursement |
|
|
Calculation |
| Local, does not call Kingdee |
Message generation |
| dry-run only, see below |
Sales/output and purchase/input invoices are not two separate endpoints; filter via
bill_type/invoice_typeonfi/invoice_fp.
⚠ Real-world constraints on reimbursement writes
The official open platform has 370 endpoints in total; the ebx module has only one GET — "reimbursement detail",
with neither a reimbursement list nor any reimbursement save endpoint.
Therefore, the "auto-fill reimbursement draft from invoice" in requirement v2.1 cannot be persisted via the open API:
kdy_fill_reimbursementonly produces pending-entry messages with tax already computed and compliance checks passed,dry_run=Falseis explicitly rejected.To actually write automatically, you can only go through non-open-API channels (RPA / frontend APIs / asking Kingdee for a custom endpoint).
Security Boundary
JDY_READONLY=true→ pure read-only.The guard layer is whitelist + deny by default: path variations (trailing slashes, sub-paths, case changes) cannot bypass it.
Payment/voucher/account writes and reimbursement submission for approval → permanently forbidden (
FORBID_ENDPOINTS), executed manually.Full audit:
kingdee_star.auditlog.
Tax Engine
Ticket type | Rule |
Special VAT invoice | Use the face tax amount and the amount excluding tax |
Passenger transport (tax shown) | Use the face tax amount; if |
Railway | ÷1.09×9% |
Air | (fare + fuel surcharge)÷1.09×9%; validate with |
Road/waterway | ÷1.03×3% |
Other ordinary invoices | Not deductible; if tax is already shown on the face, raise a prompt asking for manual confirmation of the ticket type |
Passenger transport deduction missing the traveler → compliance check marks it as non-deductible. Negative (red-letter) invoices are rejected outright.
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设计为只读为主,写入受控,基本满足需求。
Maintenance
Related MCP Connectors
Read-only MCP access to your DEXUN AdWhiz account: ad accounts, AI recommendations, savings.
Discover, plan and run tools across your connected business systems through one OAuth MCP endpoint
Read-only access to your business finances: invoices, customers, vendors, taxes, profitability.
Read PaySpace employees, organization, payroll runs, payslips and leave records. Read-only.
Related MCP Servers
- FlicenseCqualityCmaintenanceEnables 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.-