Splitwise MCP

🚀 Splitwise MCP Server

Model Context Protocolを介して35のSplitwise APIツールを公開するRuby MCPサーバーです。Claude Code、Claude Desktop、Cursorなど、MCP互換のクライアントと連携します。

🚀 クイックスタート

このサーバーを使用するには、まず必要な前提条件を満たし、インストールを行い、APIキーを取得して設定する必要があります。以下に手順を詳しく説明します。

✨ 主な機能

• 35のSplitwise APIツールを公開し、MCP互換のクライアントと連携可能。
• ユーザー、経費、グループ、友達などの情報を管理するための各種ツールを提供。
• キャッシュ機能を備え、パフォーマンスを向上させる。

📦 インストール

前提条件

• 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"ブロックを介してキーを渡すことができます。

💻 使用例

基本的な使用法

以下は、このMCPサーバーで使用できるいくつかのプロンプトの例です。

Johnは私にいくら借りていますか？

これが請求書の画像です — NYC旅行グループの私、John、Sarahの間で分割します。私はバーガーを食べ、Johnはパスタを食べ、Sarahはサラダを食べました。

先月のルームメイトグループのすべての経費を表示してください。

'Goa Trip'という名前の新しいグループを作成し、john@example.comとsarah@example.comを追加してください。

昨日の重複したランチの経費を削除してください。

私の最近の通知は何ですか？

Sarahとの残高を表示してください。

これがレシートの写真です — それを読み取り、私とルームメイトの間で経費を分割して追加してください。

高度な使用法

MCP Inspectorを使用したテスト

npx @modelcontextprotocol/inspector ruby server.rb

📚 詳細ドキュメント

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"
      }
    }
  }
}

利用可能なツール (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         # 経費のCRUD + 削除解除
        ├── friend_tools.rb          # 友達のCRUD
        ├── group_tools.rb           # グループのCRUD + メンバー管理
        ├── notification_tools.rb    # 通知の取得
        ├── resolution_tools.rb      # 友人、グループ、カテゴリの解決
        ├── user_tools.rb            # 現在のユーザーの取得、ユーザーの取得、ユーザーの更新
        └── utility_tools.rb         # カテゴリと通貨の取得