splitwise-mcp

Splitwise MCP

一个 模型上下文协议 服务，可将 Claude 连接到 Splitwise，让你通过自然语言访问自己的支出、群组、好友和余额。

警告

由 AI 开发的项目。 此代码库完全由 Claude Code 构建并积极维护。没有任何人工审查过其实现。使用前请检查所有代码和工具权限。

你可以做什么

你可以向 Claude 提出如下请求：

• “我欠了多少钱？”
• “在度假群组中添加一笔 50 美元的晚餐支出”
• “和 Sarah 按 60/40 分摊这笔酒店账单”
• “旅行群组里有哪些人？”
• “将 Meredith 添加到家庭群组”
• “显示近期支出”
• “删除那笔重复的支出”
• “下载那笔酒店支出的收据”
• “将那张 Amazon 订单截图添加为水壶支出的收据”
• “记录 250.01 美元的营地费用，由 Alison 付款，按 50/50 分摊”
• “查找今年所有包含‘egan’的支出，包括已删除的支出，并说明删除原因”

要求

• Claude Desktop 或 Claude Code
• Node.js 22 或更高版本
• Splitwise 账号和 API 密钥

条款确认

使用此 MCP 服务，即表示你确认并同意以下内容：

1. 此服务通过 Splitwise 官方开发者 API 访问你自己的 Splitwise 账号。 身份验证使用你自己的 API consumer key + secret；注册应用时，Splitwise 会向你签发这些凭据。它不会，也无法访问其他人的支出或群组。

2. 你使用此服务须遵守 Splitwise 开发者条款。与此最相关的条款如下：

你将仅在开发、测试和支持软件应用与 Splitwise 之间的自助式集成所必需的范围内使用 Splitwise 材料……

关于速率限制：“你不得以超出速率限制或构成过度或滥用使用的方式使用 API。” 关于竞争性使用：“你不得使用 Splitwise 材料创建复制 Splitwise 现有功能或与 Splitwise 竞争的应用。”

每次调用此服务中的工具时，你都表示同意这些条款——维护者于 2026-05-23 阅读了这些条款。

3. 仅限个人非商业用途。 此项目与 Splitwise, Inc. 无关，未获其认可或赞助，也未与其建立合作关系。它是一个个人自动化工具，只会在你自己的账号上调用有文档说明的 Splitwise 公共 REST API。请勿将其用于 Splitwise 数据的商业化、与 Splitwise 产品竞争，或向第三方分享 API 凭据。

4. 你的 API 密钥仅归你所有。 Splitwise 会为每个应用和开发者分别签发凭据。请勿将 SPLITWISE_API_KEY（或 consumer key/secret）提交到 git、粘贴到共享聊天中，也不要将其嵌入公共客户端。

5. 你须对使用此服务并关联自己的 Splitwise 账号所产生的任何后果承担全部责任，包括速率限制、API 密钥撤销、账号警告或任何执法措施。如果 Splitwise 对你的使用提出异议，或你的使用超出其速率限制，请停止使用此服务。

本节是维护者本着诚信对相关条款所作的摘要；它不构成法律建议，也不会修改或取代 Splitwise 的实际开发者条款。

安装

选项 A -- npx（推荐）

npx -y splitwise-mcp

添加到你的 Claude 配置（.mcp.json 或 Claude Desktop 配置）中：

{
  "mcpServers": {
    "splitwise": {
      "command": "npx",
      "args": ["-y", "splitwise-mcp"],
      "env": {
        "SPLITWISE_API_KEY": "your-api-key-here"
      }
    }
  }
}

选项 B —— 从源代码安装

git clone https://github.com/chrischall/splitwise-mcp.git
cd splitwise-mcp
npm install
npm run build

添加到 Claude Desktop 配置：

• Mac： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "splitwise": {
      "command": "node",
      "args": ["/absolute/path/to/splitwise-mcp/dist/index.js"],
      "env": {
        "SPLITWISE_API_KEY": "your-api-key-here"
      }
    }
  }
}

获取 API 密钥

1. 前往 secure.splitwise.com/apps/register
2. 注册一个应用（名称和描述可以随意填写）
3. 从应用详情页复制 API 密钥

凭据

环境变量	必填	备注
SPLITWISE_API_KEY	是	来自 splitwise.com/apps/register 的 API 密钥
SPLITWISE_OUTPUT_DIR	否	sw_get_receipt 写入下载收据的位置（仅所有者可访问，模式为 0600）。默认为 ~/Downloads/splitwise-mcp，绝不会使用工作目录。设置后，每次调用的 output_dir 必须位于此目录内。
SPLITWISE_INPUT_DIR	否	receipt.path 唯一可读取的目录（拒绝 .. 和指向目录外部的符号链接）。未设置——托管服务上始终如此——表示收据只能通过 upload_id（托管服务）或 base64 提交。
MCP_BLOB_BASE_URL / MCP_BLOB_SIGNING_KEY	否	由托管服务上的 mcp-host 注入；设置后会启用 sw_get_upload_url。本地不会设置。

确认

每次 Splitwise 写入操作（创建、编辑或删除费用、群组、好友、评论或个人资料）都会通知其他人，因此会先要求你确认。能够显示确认提示词的客户端（Claude Code）会显示确认提示词（除非 MCP_CONFIRM_ELICITATION=off）。对于无法显示确认提示词的客户端（claude.ai、Claude Desktop），首次调用不会更改任何内容，而是返回将要发送内容的完整预览以及一个 confirmToken；只有使用该令牌再次调用才会执行操作。如果期间请求中的任何内容发生变化，令牌将被拒绝。

要在此类客户端上减少调用次数：sw_confirm({confirmToken}) 只需令牌即可完成任何已预览的写入操作（服务端已保存参数，因此无需再次发送收据字节），而 sw_batch({ops}) 可一次预览并批准多项费用／评论写入操作——例如，创建费用，然后对此费用发表评论并附上收据，使用 refs: {"expense_id": "0.expense_id"}。批处理按顺序执行，并在首次失败时停止（不会回滚；结果会说明已应用的操作）。

变量	默认值
MCP_CONFIRM_MODE	ask-user	在无法显示确认提示词的客户端（claude.ai、Claude Desktop）上，写入操作的处理方式。ask-user：分两步执行——首次调用不做任何更改，返回预览和令牌；模型必须先在聊天中征得你的批准，然后才能使用该令牌再次调用。auto：同样分两步执行，但模型检查预览后可以使用令牌。refuse：此类客户端上的写入操作会被拒绝。能够显示提示词的客户端（Claude Code）始终会显示实际提示词，除非 MCP_CONFIRM_ELICITATION=off。无法识别的值按 refuse 处理。
MCP_CONFIRM_ELICITATION	on	off 表示绝不显示确认提示词，因此所有客户端都会遵循 MCP_CONFIRM_MODE 的行为。如果某个客户端声称能够显示提示词，但实际从不显示（写入操作会挂起——opencode 2.0.x），请为该客户端设置此变量。任何其他值都按 on 处理，并在 stderr 上显示警告。
MCP_CONFIRM_TTL_SECONDS	600	令牌的有效时长。
MCP_CONFIRM_SECRET	每个进程随机生成	签名密钥；只有在令牌需要跨服务端重启继续有效时才设置。

可用工具

6 个领域共 31 个工具。所有工具均以 sw_ 为前缀。

用户

工具	功能
sw_get_current_user	获取已通过身份验证的用户资料
sw_healthcheck	验证 API 密钥和 Splitwise 的连通性；指出其中哪项验证失败
sw_get_user	按 ID 获取其他用户的资料
sw_update_user	更新当前用户的姓名、区域设置或默认货币（无法在此处更改登录邮箱和密码）

群组

工具	功能
sw_list_groups	列出所有群组及其成员
sw_get_group	获取群组详情，包括成员和余额
sw_create_group	创建新群组
sw_delete_group	软删除群组
sw_undelete_group	恢复已删除的群组
sw_add_user_to_group	将用户添加到群组
sw_remove_user_from_group	将用户从群组中移除

好友

工具	功能
sw_list_friends	列出所有好友
sw_create_friend	通过电子邮件添加好友
sw_delete_friend	删除好友关系

费用

工具	功能
sw_list_expenses	列出或搜索费用。支持 Splitwise 侧的筛选条件（群组、好友、日期），以及 description_contains、include_deleted（true/false/"only"）、created_by、min_cost/max_cost 和 category；使用 next_cursor 分页；设置 view: "rows" 可查看每笔费用占一行的对账视图，设置 include_comments: true 可了解条目被删除的原因
sw_get_expense	获取单笔费用的完整详情（简洁模式包括 deleted_by、updated_by 和 has_receipt）
sw_create_expense	创建费用——可使用 split_equally、搭配 paid_by（由他人付款）的 split: "equal"，或自定义 users 分摊；category 可按名称指定，也可根据类似费用推断；预览会提示 possible_duplicates；可选添加收据
sw_update_expense	编辑现有费用，或附加／替换其收据。如果费用已删除，则会立即拒绝操作
sw_delete_expense	软删除费用
sw_undelete_expense	恢复已删除的费用，然后重新读取；返回 post_state，如果费用仍处于删除状态，则会指出重新删除它的用户
sw_attach_receipt	为现有费用附加或替换收据，不更改其他内容
sw_get_comments	获取费用的评论
sw_create_comment	为费用添加评论
sw_delete_comment	删除评论

确认

工具	功能
sw_confirm	仅凭预览写入操作时获得的 confirmToken 完成该操作
sw_batch	在一次预览和一次批准中执行多项费用／评论写入操作；后续操作可使用较早操作生成的 expense_id

收据

工具	功能
sw_get_receipt	使用服务端凭据下载费用的收据图片／PDF。可内联返回（inline）、作为提取的 PDF 文本返回（extract_text），和／或写入文件
sw_get_upload_url	仅托管版本支持：获取短时有效的签名 URL，用于通过 curl -X PUT 上传收据文件，然后传入 receipt: {upload_id, filename}；无需通过对话传输 base64

实用工具

工具	功能
sw_get_notifications	查看近期活动动态
sw_get_categories	获取费用类别列表
sw_get_currencies	获取支持的货币代码

故障排除

“SPLITWISE_API_KEY is required” —— 在 MCP 配置或 .env 文件中设置此环境变量。

附加收据 —— sw_create_expense、sw_update_expense 和 sw_attach_receipt 接受 receipt: { base64, filename, mime_type? }（可在任何环境中使用，包括托管的服务），或者在设置了 SPLITWISE_INPUT_DIR 的本地服务上，接受 receipt: { path, filename }，用于指定该目录中的文件。支持最大 10 MiB 的 PNG、JPEG、GIF 或 PDF（Splitwise 未说明大小限制）；类型会根据字节内容检测，如果 mime_type 与检测结果不一致，则会拒绝。确认预览会显示文件名、类型、大小和 SHA-256，而非文件内容，并且令牌会绑定到这些字节。写入后，工具会检查 Splitwise 是否确实存储了该文件（receipt.original）；如果没有，会返回一条指出费用编号的错误。收据会替换费用中已有的任何收据。

打开收据 URL 时出现 401 —— 费用中的 receipt.original / receipt.large URL 并非公开 URL；访问它们需要 API 密钥。请使用 sw_get_receipt，不要直接获取这些 URL。

收据保存到了无法读取的位置 —— sw_get_receipt 会将文件写入服务端文件系统；如果服务由托管或容器化运行，该文件系统并非调用方的文件系统。传入 inline: true 可获取字节内容（图片以图像块形式返回，PDF 以嵌入式资源形式返回），或传入 extract_text: true 获取 PDF 文本。使用 inline 或 extract_text 且未指定 output_dir 时，除非同时传入 write: true，否则不会写入任何内容。传入 write: false 可跳过写入；如果写入本身失败（文件系统为只读），只要你请求了内容，调用仍会成功，并将 write_error 作为报告返回。

429 速率限制 —— Splitwise 的速率限制未公开说明。请稍等片刻后重试。

Claude 中未显示工具 —— 前往 Claude Desktop > Settings > Developer 查看已连接的服务。编辑配置后，请确保完全退出并重新启动应用。

开发

npm test        # tsc typecheck + run the test suite (vitest)
npm run build   # compile TypeScript -> dist/

项目结构

src/
  client.ts         Splitwise API client (auth, request handling)
  index.ts          MCP server entry point
  tools/
    user.ts         sw_get_current_user, sw_get_user
    healthcheck.ts  sw_healthcheck
    groups.ts       group CRUD and membership
    friends.ts      friend list and management
    expenses.ts     expense CRUD
    receipts.ts     authenticated receipt download + PDF text extraction
    utilities.ts    notifications, categories, currencies, comments
    _confirm.ts     confirmation gate shared by every write

许可证

MIT