purchase-app-mcp

把「个人管家」App 的采购 / 记账 / 待办 / 项目 / 预算 / 统计数据以 MCP 工具暴露给任意 agent（Claude Code、Cursor、IDE agent、自建 agent 均可）。

每个安装实例用自己的 App 账号登录，凭据只存本机；仓库里没有任何硬编码 token / 密码 / 服务端密钥。

给 agent：一次性安装链接（全自动，推荐）

App v3.0.1+ 的「设置 → 连接 Agent（MCP）」可以生成一条形如 https://<你的App>/agent#t=<票据> 的链接。把链接交给 agent，它只需要运行：

npx -y github:begin2019510/purchase-app-mcp install "<链接>"

这一条命令会：

1. 注册 MCP 并安装 skill（等价于 setup）；

2. 用票据向 App 换取该安装实例独立的 refresh token；

3. 调用 purchase.list 做一次只读验证，成功时输出 INSTALL_OK。

链接 10 分钟内有效、只能兑换一次；生成新链接会让该账号之前未使用的链接立即失效。票据放在 URL 的 # 片段中，不会随请求出现在服务器日志或 Referer 里。

全程不需要 App 密码，agent 也不应索要密码。每个 agent 用各自生成的链接，就得到各自独立的凭据，可以单独 logout 吊销。

已登录的安装也可以为另一个 agent 生成链接：

npx -y github:begin2019510/purchase-app-mcp link
# 输出 JSON：{ "ok": true, "url": "...", "expiresAt": "...", "command": "..." }

给 agent 的完整安装/使用规则见 AGENTS.md。

Related MCP server: Qianji Bridge MCP Server

给 agent：skill 链接（另一种方式）

把下面任一链接发给 agent：

• https://github.com/begin2019510/purchase-app-mcp/blob/main/skills/purchase-app/SKILL.md

• raw：https://raw.githubusercontent.com/begin2019510/purchase-app-mcp/main/skills/purchase-app/SKILL.md

agent 读取后会执行 npx -y github:begin2019510/purchase-app-mcp setup：自动注册 MCP、把 skill 安装到 ~/.claude/skills/purchase-app/，然后引导用户完成一次登录。

MCP 提供工具，skill 提供「安装 + 登录 + 验证 + 安全使用」步骤。skill 本身不接触密码或 token。

安全模型（如何保证受信）

信任边界：安装了这个 MCP 且完成登录的 agent，拥有该 App 账号的数据读写权限。请只在自己信任的 agent 中配置；不再使用时执行 logout。

安装

要求：Node.js >= 18.17；安装时需要能访问 GitHub 和 npm registry（本机 npm 已配置 npmmirror 时更快）。MCP 只访问你自己的 App 地址，不依赖本仓库的服务器。

一键 setup（推荐）

npx -y github:begin2019510/purchase-app-mcp setup

• Claude Code：用官方 CLI 注册为用户级 MCP，并安装 skill；

• 已注册则跳过，幂等；

• 只写配置和 skill，不登录、不写凭据；

• 其他 agent / 只看配置：

npx -y github:begin2019510/purchase-app-mcp setup --print

输出纯 JSON（mcpServers.purchase-app + skill 路径/链接 + 命令），不写任何文件。也可以直接写指定的 JSON 配置：

npx -y github:begin2019510/purchase-app-mcp setup --agent json --config <配置文件路径>

每个 agent 独立凭据：加 --home <独立目录>，然后分别登录。

Claude Code（手动）

claude mcp add purchase-app -s user \
  -e PURCHASE_APP_MCP_HOME=$HOME/.config/purchase-app-mcp \
  -- npx -y github:begin2019510/purchase-app-mcp

通用 MCP 客户端（JSON）

{
  "mcpServers": {
    "purchase-app": {
      "command": "npx",
      "args": ["-y", "github:begin2019510/purchase-app-mcp"]
    }
  }
}

Cursor：写入 ~/.cursor/mcp.json；其他客户端使用各自的 mcpServers 配置格式。

从源码运行

git clone https://github.com/begin2019510/purchase-app-mcp.git
cd purchase-app-mcp
npm install
node bin/purchase-app-mcp.js login

登录（有两条路，二选一）

• 有安装链接：用上面的 install "<链接>"，不需要密码，也不需要本机浏览器。

• 本机登录（没有链接时）：

npx -y github:begin2019510/purchase-app-mcp login

有图形界面（macOS、Windows、Linux 的 DISPLAY/WAYLAND_DISPLAY）时会自动打开浏览器；否则终端打印 http://127.0.0.1:<port>/login/<一次性随机串>，在浏览器打开并输入 App 账号（默认 admin）和密码。可用 --no-open 禁止自动打开。

• 密码只用于向 App 的 HTTPS 登录接口换取 token，不会保存。

• 只把 refresh token 写入 ~/.config/purchase-app-mcp/auth.json（目录 0700、文件 0600）。

• access token 24 小时有效、自动续期；refresh token 30 天有效、每次续期轮换。

• 登录后无需重启 agent：MCP 进程会在下一次工具调用时自动读取新凭据。

无浏览器的服务器（推荐用安装链接，见文首；没有链接时二选一）：

# 方式 0（推荐）：让用户在 App 设置页生成一次性安装链接，然后
npx -y github:begin2019510/purchase-app-mcp install "<链接>"

# 方式 1：SSH 端口转发（login 会打印实际端口）
ssh -L 127.0.0.1:<port>:127.0.0.1:<port> user@server
# 然后在本地浏览器打开 login 打印的地址

# 方式 2：一次性环境变量登录（密码不落盘，注意 shell 历史/进程环境）
read -rs PURCHASE_APP_PASSWORD
export PURCHASE_APP_PASSWORD
npx -y github:begin2019510/purchase-app-mcp login
unset PURCHASE_APP_PASSWORD

多 agent 隔离（推荐）

默认所有 agent 共用当前系统用户的凭据目录。若希望每个 agent 独立登录、独立吊销，在各自的 MCP 配置里指定独立目录：

{
  "mcpServers": {
    "purchase-app": {
      "command": "npx",
      "args": ["-y", "github:begin2019510/purchase-app-mcp"],
      "env": {
        "PURCHASE_APP_MCP_HOME": "/home/me/.config/purchase-app-mcp/work-agent"
      }
    }
  }
}

然后分别执行：

PURCHASE_APP_MCP_HOME=/home/me/.config/purchase-app-mcp/work-agent \
  npx -y github:begin2019510/purchase-app-mcp login

共用同一目录也安全：refresh token 轮换有跨进程文件锁，不会互相踢下线；只是无法按 agent 单独吊销。需要单独吊销时用独立目录。

常用命令

npx -y github:begin2019510/purchase-app-mcp install "<链接>"  # 一次性链接：注册 + 授权 + 只读验证
npx -y github:begin2019510/purchase-app-mcp link              # 生成给别人用的一次性安装链接
npx -y github:begin2019510/purchase-app-mcp status            # 查看登录状态、凭据路径
npx -y github:begin2019510/purchase-app-mcp logout            # 删除本机凭据并吊销服务端 refresh token
npx -y github:begin2019510/purchase-app-mcp login             # 本机网页登录（有桌面自动开浏览器）

环境变量

工具（27 个）

• 采购：purchase.list purchase.get purchase.create purchase.update purchase.delete

• 记账：expense.list expense.create expense.update expense.delete

• 待办：todo.list todo.create todo.update todo.delete

• 项目：project.list project.get project.create project.update project.delete phase.list phase.status.set

• 预算：budget.get budget.save

• 重复项 / 分类：recurring.list recurring.update cats.list cats.update

• 统计：analytics.summary（月度收入、采购、净支出、分期、预算使用率、分类 TOP、环比）

写操作全部走 App 真实业务 API，服务端的状态联动（审批、待办生成、分期、预算规则等）照常生效。

阶段工具与版本要求

phase.list 与 phase.status.set 都走 App 公网 API。App 3.0.0+（2026-10 版本线重置；此前 4.0.52–4.0.61 同样包含）已部署 /api/phases 与 /api/phase-items，阶段状态/规划时间/交付物均可用。

如果调用返回「接口返回了网页而不是 JSON」，说明目标 App 的部署版本过旧（缺少阶段端点）；先升级 App。旧部署也可临时使用仓库内的 app-patch/functions/api/phases.js 补丁，但不再推荐。

数据与隐私

本 MCP 不收集、不上传任何数据；所有请求直接从你的机器发往你自己的 App 地址（默认 https://121212121.top）。凭据与审计日志只保存在本机。

License

MIT