Skip to main content
Glama
kingdee_star

kingdee_star

by adambbhe

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

JDY_CLIENT_ID / JDY_CLIENT_SECRET

X-Api-ClientID header + HMAC key for X-Api-Signature

Tenant account set

JDY_APP_KEY / JDY_APP_SECRET

Compute app_signature, exchange for app-token

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-Addr

Three easy pitfalls (already handled in signer.py; read the comments before changing anything):

  1. hash_hmac(..., raw_output=false) returns a hex string; the base64 input is this hex, not the raw digest.

  2. 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.

  3. X-GW-Router-Addr (taken from the domain in 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-run

On 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        # stdio

Merge 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

kdy_health kdy_auth_fetch_token

—

Probe

kdy_current_user

sys/current_user_info

Read-only · Accounts

kdy_list_account kdy_list_account_type

fi/account fi/account_type

Read-only · Vouchers

kdy_list_voucher kdy_get_voucher

fi/voucher fi/voucher_detail

Read-only · Invoices

kdy_list_invoice kdy_get_invoice

fi/invoice_fp fi/invoice_detail

Read-only · Receipts/Payments

kdy_list_ar_receive kdy_list_ap_pay

arap/ar_credit arap/ap_credit

Read-only · Transactions

kdy_reconciliation kdy_customer_debt

arap/reconciliation_statement arap/customer_debt

Read-only · Reimbursement

kdy_get_reimb_detail kdy_list_expense

ebx/reimb_detail (list endpoint does not exist)

Calculation

kdy_calc_invoice_tax

Local, does not call Kingdee

Message generation

kdy_fill_reimbursement

dry-run only, see below

Sales/output and purchase/input invoices are not two separate endpoints; filter via bill_type / invoice_type on fi/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_reimbursement only produces pending-entry messages with tax already computed and compliance checks passed, dry_run=False is 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.audit log.

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 face_tax is missing, raise an explicit error — no silent downgrade

Railway

÷1.09×9%

Air

(fare + fuel surcharge)÷1.09×9%; validate with taxable_base() rather than total

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 tools
kdy_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

    A3.5/5.0

    Scored across 17 tools

    Disambiguation5/5

    每个工具针对明确的资源或操作:健康检查、令牌获取、用户、科目、凭证、发票、收付款、对账、余额、报销、税务计算和填写。list_与get_工具清晰区分实体层级,没有两个工具做同一件事。

    Naming Consistency4/5

    大多数工具采用 'kdy_动词_名词' 模式,如 list_account, get_voucher, calc_invoice_tax。少数如 reconciliation 和 customer_debt 省略动词,但仍是可读的名称,整体风格基本统一,仅有轻微不一致。

    Tool Count4/5

    17个工具对于财务查询域来说略多,但每个工具覆盖了必要的实体和操作,没有冗余。这个数量在合理范围内,略超出典型的最优区间但完全可接受。

    Completeness4/5

    覆盖了核心财务实体(科目、凭证、发票、收付款、对账、客户欠款、报销)的查询和详情,并提供了税务计算和受控写入凭证代填。缺少更新删除操作,但该API设计为只读为主,写入受控,基本满足需求。

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      C
      quality
      C
      maintenance
      Enables read-only querying of Kingdee's Three-Effect project management system, covering projects, reimbursements, loans, payments, working hours, and budgets, via MCP tools.
      28
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -