金大哥 - splitwise_mcp MCP 详情

article

README

🚀 Splitwise MCP 服务器

这是一个 Ruby MCP 服务器，通过 Model Context Protocol 提供 35 个 Splitwise API 工具。它可以与任何兼容 MCP 的客户端配合使用，如 Claude Code、Claude Desktop、Cursor 等。

🚀 快速开始

前提条件

Ruby 3.x
Bundler

📦 安装指南

# 若未安装 Homebrew，则进行安装
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

brew install ruby
git clone https://github.com/imtheaman/splitwise_mcp.git
cd splitwise_mcp
bundle install
cp .env.example .env   # 可选 — 仅在使用 MCP Inspector 或独立使用时需要

如果使用 .env 文件，请编辑它并添加你的 Splitwise API 密钥。当使用 MCP 客户端（如 Claude Code、Cursor 等）时，你可以通过客户端配置中的 "env" 块传递密钥。

获取 API 密钥

在 https://secure.splitwise.com/apps 注册一个应用。
在应用的详情页面，生成一个个人 API 密钥。
或者，使用 OAuth 2.0 访问令牌。

🔧 配置

| 属性 | 是否必需 | 默认值 | 详情 | |------|----------|---------|-------------| | SPLITWISE_API_KEY | 是* | — | 个人 API 密钥 | | SPLITWISE_OAUTH_ACCESS_TOKEN | 是* | — | OAuth 2.0 访问令牌 | | SPLITWISE_CACHE_TTL | 否 | 86400 | 缓存的生存时间（秒） | | SPLITWISE_MATCH_THRESHOLD | 否 | 70 | 模糊匹配阈值（0 - 100） | | SPLITWISE_RESOLVER_CACHE_TTL | 否 | 300 | 解析器缓存的生存时间（秒） |

* SPLITWISE_API_KEY 或 SPLITWISE_OAUTH_ACCESS_TOKEN 其中之一是必需的。

不同客户端的设置

Claude Code 设置

将以下内容添加到你的 ~/.mcp.json 文件中：

{
  "mcpServers": {
    "splitwise_mcp": {
      "command": "ruby",
      "args": ["server.rb"],
      "cwd": "/path/to/splitwise-mcp",
      "env": {
        "SPLITWISE_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Claude Desktop 设置

将以下内容添加到你的 claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "splitwise_mcp": {
      "command": "ruby",
      "args": ["server.rb"],
      "cwd": "/path/to/splitwise-mcp",
      "env": {
        "SPLITWISE_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Cursor 设置

将以下内容添加到你的项目级 .cursor/mcp.json 或全局 ~/.cursor/mcp.json 文件中：

{
  "mcpServers": {
    "splitwise_mcp": {
      "command": "ruby",
      "args": ["server.rb"],
      "cwd": "/path/to/splitwise-mcp",
      "env": {
        "SPLITWISE_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

💻 使用示例

以下是一些可以与该 MCP 服务器一起使用的示例提示：

John 欠我多少钱？

这是账单图片 — 在纽约之旅小组中，将费用在我、John 和 Sarah 之间分摊。我吃了汉堡，John 吃了意大利面，Sarah 吃了沙拉

显示室友小组上个月的所有费用

创建一个名为 '果阿之旅' 的新小组，并添加 john@example.com 和 sarah@example.com

删除昨天重复的午餐费用

我最近的通知有哪些？

显示我与 Sarah 的余额

这是收据的照片 — 读取它并添加我和室友之间分摊的费用

MCP 检查器

使用 MCP 检查器以交互方式测试工具：

npx @modelcontextprotocol/inspector ruby server.rb

📚 详细文档

可用工具（35 个）

| 类别 | 工具 | |----------|-------| | 用户 (3) | GetCurrentUser、GetUser、UpdateUser | | 费用 (6) | GetExpenses、GetExpense、CreateExpense、UpdateExpense、DeleteExpense、UndeleteExpense | | 小组 (7) | GetGroups、GetGroup、CreateGroup、DeleteGroup、UndeleteGroup、AddUserToGroup、RemoveUserFromGroup | | 朋友 (5) | GetFriends、GetFriend、CreateFriend、CreateFriends、DeleteFriend | | 评论 (3) | GetComments、CreateComment、DeleteComment | | 通知 (1) | GetNotifications | | 解析 (3) | ResolveFriend、ResolveGroup、ResolveCategory | | 实用工具 (2) | GetCategories、GetCurrencies | | 算术 (5) | AddTool、SubtractTool、MultiplyTool、DivideTool、ModuloTool |

项目结构

splitwise-mcp/
├── server.rb                        # 入口点 — 注册工具，启动 MCP 服务器
├── Gemfile                          # 依赖项
├── .env.example                     # 环境变量模板
├── openapi.json                     # Splitwise OpenAPI 规范（参考）
└── lib/
    ├── cache.rb                     # 内存中的 TTL 缓存
    ├── client.rb                    # Splitwise HTTP 客户端
    ├── errors.rb                    # 自定义错误类
    ├── resolver.rb                  # 模糊名称到 ID 的解析
    ├── validators.rb                # 输入验证辅助工具
    └── tools/
        ├── arithmetic_tools.rb      # 加法、减法、乘法、除法、取模
        ├── comment_tools.rb         # 获取评论、创建评论、删除评论
        ├── expense_tools.rb         # 费用的增删改查及恢复
        ├── friend_tools.rb          # 朋友的增删改查
        ├── group_tools.rb           # 小组的增删改查及成员管理
        ├── notification_tools.rb    # 获取通知
        ├── resolution_tools.rb      # 解析朋友、小组、类别
        ├── user_tools.rb            # 获取当前用户、获取用户、更新用户
        └── utility_tools.rb         # 获取类别、获取货币

splitwise_mcp