# kingdee-mcp-proxy 🐟

**Production-grade MCP proxy that lets AI Agents (Claude / Cursor / any MCP client) safely query Kingdee Cloud Galaxy (金蝶云星空) ERP — with read-only mode, write confirmation gates, and full audit logging.**

让 AI Agent 用自然语言安全查询/操作金蝶云星空 ERP：只读模式、写操作确认闸门、全链路审计日志。

[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-green.svg)]()
[![MCP](https://img.shields.io/badge/Protocol-MCP-purple.svg)]()

> ⚡ **Battle-tested**: running in production since Aug 2026, querying real ERP data daily via official Kingdee OpenAPI (`ExecuteBillQuery`).

---

## Why this exists

Community MCP connectors for Kingdee typically hand the AI a **master key**: admin credentials, raw secrets in prompts, unrestricted writes, no audit trail. That's how you get an AI deleting your purchase orders.

This project takes the **zero-trust** approach:

| Risk | Common approach | This proxy |
|------|----------------|------------|
| Credentials | Secrets exposed to LLM context | Keys live only server-side in `.env`, **never enter model context** |
| Permissions | Admin/SA account | Dedicated least-privilege integration account |
| Write ops | AI can save/submit/audit/delete directly | `READONLY=true` → write tools are **physically not registered**; when enabled: `preview → human confirm → execute` |
| Data leakage | Raw tables dumped to external LLM | Aggregation at proxy; forced `LIMIT` (default 100, max 1000) |
| Audit | None | Append-only audit log: who / which tool / sanitized params / row count / latency |

## Quick start

```bash
git clone https://github.com/zhigang327/kingdee-mcp-proxy.git
cd kingdee-mcp-proxy
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env   # fill in your Kingdee integration account
python -m proxy.server              # stdio mode (Claude Desktop / WorkBuddy)
python -m proxy.server --transport sse --host 0.0.0.0 --port 8181   # team-shared SSE mode
```

Point your MCP client at it:

```json
{ "mcpServers": { "kingdee": {
    "command": "python",
    "args": ["/path/to/proxy/server.py"],
    "env": { "READONLY": "true" } } } }
```

Then just ask: *"查一下上个月的物料入库单"* → done.

## Tools

**Read-only:** `query_bill` (generic bill query) · `view_bill` (bill detail) · `health`

**Write** (only registered when `READONLY=false`, always gated):
`preview_save_bill` → `preview_submit_bills` → `preview_audit_bills` → `confirm_action`

## Setup on Kingdee side (5 min)

1. 金蝶后台：`系统管理 → 第三方系统登录授权 → 新增`
2. Create a dedicated integration account (**not** Administrator), grant only needed query modules
3. Copy AppID / AppSecret / AcctID into `.env`

Full checklist: see [安全核对清单](docs/checklist.md) *(WIP)*

## Business value / 商业价值

- For CFOs/IT managers: give every employee an AI analyst over ERP data without opening security holes
- Works with: Claude Desktop, Cursor, WorkBuddy, or any MCP-compatible agent
- I also do **custom ERP×AI integrations** (UFIDA/SAP/self-built systems): → contact below

## Dual licensing

- **Open source**: AGPL-3.0
- **Commercial license** available if you need to embed this in closed-source products or want SLA support → open an issue titled `[commercial]`

## Contact · ERPilot 企航智能

> **ERPilot** — We pilot AI into your business systems. 让 AI 开进你的业务系统。

- Issues & PRs welcome
- Custom integration inquiries (UFIDA / SAP / self-built ERP): open an issue titled `[integration]`
- 定制企业 AI 落地（MCP 开发 / 私有化部署 / Agent 工作流）：请提 issue


---

⭐ **If this saved you a week of work, star the repo — it helps other Chinese ERP teams find it.**