# Xero MCP Server

Xero Accounting API 的 MCP (Model Context Protocol) 服务器，让 Claude Desktop 用自然语言操作 Xero 云会计系统。

## 功能

### 读取（9 个工具）
- 组织信息、联系人、科目表、发票、银行交易、付款、贷项通知单、产品目录、手工日记账
- 审计轨迹查询

### 写入（6 个工具）
- 创建联系人、发票、银行交易、手工日记账
- 记录付款、上传附件

### 报表（4 个工具，本地计算）
- 试算平衡表、应收账款账龄、应付账款账龄、损益表

## 两种运行模式

### 本地 STDIO 模式

```bash
pip install -r requirements.txt

# 设置环境变量
export XERO_CLIENT_ID=xxx
export XERO_CLIENT_SECRET=xxx
export XERO_TENANT_ID=xxx
export XERO_REFRESH_TOKEN=xxx

python server.py
```

Claude Desktop 配置见 [claude_desktop_config_example.json](claude_desktop_config_example.json)

### 远程 HTTP 模式（多租户）

```bash
cp .env.example .env
# 编辑 .env 填写凭证和域名

docker compose up -d --build
```

详细部署教程见 [部署教程.md](部署教程.md) 和 [Claude_Desktop_MCP配置教程.md](Claude_Desktop_MCP配置教程.md)

## 架构

```
Claude Desktop ──HTTPS──▶ Nginx ──HTTP──▶ MCP Server ──OAuth 2.0──▶ Xero API
```

- Nginx 负责 SSL 终结和反向代理
- MCP Server (Starlette + uvicorn) 处理 MCP 协议
- 多租户通过 API Key 隔离，OAuth Token 存在 SQLite

## 文件说明

| 文件 | 用途 |
|------|------|
| `server.py` | 本地 STDIO 模式入口 |
| `server_remote.py` | 远程 HTTP 多租户模式入口 |
| `xero_client.py` | Xero API 客户端，自动刷新 Token |
| `aggregations.py` | 本地报表计算（试算平衡/账龄/损益） |
| `Dockerfile` / `docker-compose.yml` | Docker 部署 |
| `部署教程.md` | 服务器部署详细步骤 |
| `Claude_Desktop_MCP配置教程.md` | Claude Desktop 配置教程（含踩坑记录） |

## 依赖

- Python 3.12+
- mcp >= 2.0.0
- uvicorn / starlette
- requests