内容
# 分账助手 MCP
[](https://github.com/chrischall/splitwise-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/splitwise-mcp)
[](LICENSE)
一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，连接 Claude 到 [Splitwise](https://www.splitwise.com)，为您提供自然语言访问您的开支、分组、好友和余额。
> [!WARNING]
> **AI 开发的项目。** 该代码库完全由 [Claude 代码](https://www.anthropic.com/claude) 构建和积极维护。没有人类审计过实现。在使用之前，请查看所有代码和工具权限。
## 您能做什么
问 Claude 如下问题：
- *"我欠多少钱？*
- *"在旅行分组中添加 50 美元的晚餐开支"*
- *"将酒店账单按 60/40 的比例与 Sarah 分割"*
- *"谁在旅行分组中？*
- *"将 Meredith 添加到家庭分组"*
- *"显示我最近的开支"*
- *"删除重复的开支"*
## 要求
- [Claude 桌面版](https://claude.ai/download) 或 [Claude 代码](https://docs.anthropic.com/en/docs/claude-code)
- [Node.js](https://nodejs.org) 20.6 或更高版本
- 一个 [Splitwise](https://www.splitwise.com) 账户和 API 密钥
## 条款确认
使用此 MCP 服务器，您确认并同意以下内容：
**1. 此服务器通过 Splitwise 的官方开发者 API 访问您自己的 Splitwise 账户。** 认证通过您自己的 API 消费者密钥 + 秘密进行，Splitwise 在您注册应用程序时为您提供。它不访问（也不能访问）其他人的开支或分组。
**2. [Splitwise 开发者条款](https://dev.splitwise.com/) 管辖您对该服务器的使用。** 这里最相关的条款：
> 您仅应将 Splitwise 材料用于开发、测试和支持您的软件应用程序的自助集成... 与 Splitwise。
以及速率限制： *"您不得以超过速率限制或构成过度或滥用使用的方式使用 API。"* 以及竞争性使用： *"您不得 [使用] Splitwise 材料创建复制现有 Splitwise 功能或与 Splitwise 竞争的应用程序。*
每次您在此服务器上调用工具时，您都同意这些条款 - 2026-05-23 由维护者阅读。
**3. 仅限个人、非商业使用。** 该项目与 Splitwise, Inc. 无关，不受其认可、赞助或合作。它是一个个人自动化工具，通过您自己的账户调用记录的公共 Splitwise REST API。不要使用它来商业化 Splitwise 数据、与 Splitwise 产品竞争或与第三方共享 API 凭证。
**4. 您的 API 密钥仅属于您。** Splitwise 按应用、开发者颁发凭证。 **不要将您的 `SPLITWISE_API_KEY`（或消费者密钥/秘密）提交到 git**，不要将其粘贴到共享聊天中，也不要将其嵌入到公共客户端中。
**5. 您对使用此服务器连接您的 Splitwise 账户所产生的一切后果承担全部责任** - 速率限制、API 密钥撤销、账户警告或任何执法行动。如果 Splitwise 对您的使用提出异议或您的使用超过其速率限制，请停止使用此服务器。
本节是维护者的善意总结条款 - 它不是法律建议，也不修改或取代 Splitwise 的实际开发者条款。
## 安装
### 选项 A -- npx（推荐）
```bash
npx -y splitwise-mcp
```
添加到您的 Claude 配置（`.mcp.json` 或 Claude 桌面版配置）：
```json
{
"mcpServers": {
"splitwise": {
"command": "npx",
"args": ["-y", "splitwise-mcp"],
"env": {
"SPLITWISE_API_KEY": "您的 API 密钥"
}
}
}
}
```
### 选项 B -- 从源代码
```bash
git clone https://github.com/chrischall/splitwise-mcp.git
cd splitwise-mcp
npm install
npm run build
```
添加到 Claude 桌面版配置：
- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"splitwise": {
"command": "node",
"args": ["/绝对路径/to/splitwise-mcp/dist/index.js"],
"env": {
"SPLITWISE_API_KEY": "您的 API 密钥"
}
}
}
}
```
### 获取您的 API 密钥
1. 前往 [secure.splitwise.com/apps/register](https://secure.splitwise.com/apps/register)
2. 注册一个应用程序（名称和描述可以是任意的）
3. 从应用程序详细信息页面复制 **API 密钥**
## 凭证
| 环境变量 | 是否必需 | 备注 |
|---------|----------|-------|
| `SPLITWISE_API_KEY` | 是 | 来自 [splitwise.com/apps/register](https://secure.splitwise.com/apps/register) 的 API 密钥 |
## 可用工具
20 个工具，涵盖 5 个领域。所有工具都以 `sw_` 为前缀。
### 用户
| 工具 | 功能 |
|------|-------------|
| `sw_get_current_user` | 获取认证用户的个人资料 |
| `sw_get_user` | 通过 ID 获取另一个用户的个人资料 |
### 分组
| 工具 | 功能 |
|------|-------------|
| `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` | 列出或搜索开支，并带有筛选器 |
| `sw_get_expense` | 单个开支的完整详情 |
| `sw_create_expense` | 创建开支（等额或自定义分割） |
| `sw_update_expense` | 编辑现有开支 |
| `sw_delete_expense` | 软删除开支 |
| `sw_undelete_expense` | 恢复已删除的开支 |
| `sw_get_comments` | 获取开支的评论 |
| `sw_create_comment` | 添加评论到开支 |
| `sw_delete_comment` | 删除评论 |
### 实用工具
| 工具 | 功能 |
|------|-------------|
| `sw_get_notifications` | 最近的活动动态 |
| `sw_get_categories` | 开支类别列表 |
| `sw_get_currencies` | 支持的货币代码 |
## 故障排除
**"SPLITWISE_API_KEY 是必需的"** -- 在您的 MCP 配置或 `.env` 文件中设置环境变量。
**429 速率限制** -- Splitwise 有未公开的速率限制。等待片刻后重试。
**工具在 Claude 中未显示** -- 进入 **Claude 桌面版 > 设置 > 开发者** 查看已连接的服务器。确保您在编辑配置后完全退出并重新启动。
## 开发
```bash
npm test # 运行测试套件（vitest）
npm run build # 编译 TypeScript -> dist/
```
### 项目结构
```
src/
client.ts Splitwise API 客户端（认证，请求处理）
index.ts MCP 服务器入口点
tools/
user.ts sw_get_current_user, sw_get_user
groups.ts 分组 CRUD 和成员管理
friends.ts 好友列表和管理
expenses.ts 开支 CRUD，评论
utilities.ts 通知，类别，货币
```
## 许可证
MIT
