# 云启智联 MCP Server

云启智联AI文档解析服务的 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 服务器，让 Claude、Cursor、Windsurf 等支持 MCP 的 AI 客户端直接调用票据识别能力。

## 功能

- `parse_bank_receipt` — 银行回单解析（支持每页多张自动裁剪）
- `parse_bank_statement` — 银行对账单解析
- `parse_invoice` — 增值税发票解析
- `parse_document` — 通用文档解析
- `get_task_result` — 查询异步任务结果

## 前置要求

1. Python 3.10+
2. 云启智联 API Key（从 [http://8.135.62.13:5000](http://8.135.62.13:5000) 注册获取）

## 安装

```bash
pip install yqzl-mcp-server
```

或从源码安装：

```bash
git clone https://github.com/yunqi-zhilian/yqzl-mcp-server.git
cd yqzl-mcp-server
pip install -e .
```

## 启动

安装后，如果 `yqzl-mcp-server` 命令可用，直接运行：

```bash
yqzl-mcp-server
```

部分环境（尤其是 Windows）安装后脚本目录可能不在 PATH 中，导致命令找不到。此时可使用 Python 模块方式启动，效果完全相同：

```bash
python -m yqzl_mcp_server.server
```

## 在 Claude Desktop 中配置

编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：

```json
{
  "mcpServers": {
    "yqzl-ai": {
      "command": "yqzl-mcp-server",
      "env": {
        "YQZL_API_BASE_URL": "http://8.135.62.13:5000/AIService"
      }
    }
  }
}
```

如果系统提示找不到 `yqzl-mcp-server` 命令（常见于 Windows），可将 `command` 改为使用 Python 模块方式启动：

```json
{
  "mcpServers": {
    "yqzl-ai": {
      "command": "python",
      "args": ["-m", "yqzl_mcp_server.server"],
      "env": {
        "YQZL_API_BASE_URL": "http://8.135.62.13:5000/AIService"
      }
    }
  }
}
```

配置完成后重启 Claude Desktop，即可在对话中让 Claude 调用票据识别工具。

## 在 Cursor 中配置

打开 Cursor Settings → MCP，添加 server：

- Type: `stdio`
- Name: `yqzl-ai`
- Command: `yqzl-mcp-server`

如果命令找不到，可改用：

- Command: `python`
- Args: `-m yqzl_mcp_server.server`

## 使用示例

对 AI 说：

> 请用云启智联解析这张银行回单 `/Users/xxx/receipt.pdf`，API Key 是 `as-xxxxxxxx`。

AI 会自动调用 `parse_bank_receipt` 工具并返回结构化结果。

## 计费说明

MCP Server 不掌握计费逻辑。所有调用都通过你的云启智联 API Key 进行，按量从你在云启智联平台的余额中扣费。具体价格见官网。

## 自定义上游地址

默认使用 `http://8.135.62.13:5000/AIService`。域名备案完成后，可通过环境变量切换：

```bash
export YQZL_API_BASE_URL="https://yunqi-zhilian.com/AIService"
```

## 开发

```bash
pip install -e ".[dev]"
python -m yqzl_mcp_server.server
```

## 许可证

MIT