Splitwise MCP

🚀 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 密鑰

1. 在 https://secure.splitwise.com/apps 註冊一個應用。
2. 在應用的詳情頁面，生成一個個人 API 密鑰。
3. 或者，使用 OAuth 2.0 訪問令牌。

🔧 配置

* 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 個）

項目結構

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         # 獲取類別、獲取貨幣