splitwise-mcp

Splitwise MCP

Claude を Splitwise に接続し、支出、グループ、友人、残高に自然言語でアクセスできる Model Context Protocol サーバーです。

警告

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 の公式 Developer API を通じて、あなた自身の Splitwise アカウントにアクセスします。 認証には、アプリを登録すると Splitwise から発行される、あなた自身の API コンシューマーキーとシークレットを使用します。他の人の支出やグループにアクセスすることはなく、またアクセスすることもできません。

2. このサーバーの使用には Splitwise の Developer Terms が適用されます。 特に関連する条項は次のとおりです。

Splitwise Materials は、Splitwise とのセルフサービス型連携を開発、テスト、サポートするために必要な範囲でのみ使用するものとします。

レート制限については、「レート制限を超える、または過度もしくは不正な使用にあたる方法で API を使用しないものとします。」 とされています。競合する使用については、「既存の Splitwise 機能を複製するアプリケーション、または Splitwise と競合するアプリケーションの作成に Splitwise Materials を使用してはなりません。」 とされています。

このサーバーのツールを呼び出すたびに、保守担当者が2026-05-23に確認したこれらの規約に同意することになります。

3. 個人利用のみとし、商用利用は禁止です。 このプロジェクトは Splitwise, Inc. と提携、承認、後援、または協力関係にありません。ご自身のアカウントで、文書化された公開 Splitwise REST API を呼び出す個人向けの自動化ツールです。Splitwise のデータを商用化したり、Splitwise の製品と競合したり、API 認証情報を第三者と共有したりするために使用しないでください。

4. API キーはあなた専用です。 Splitwise はアプリごと、開発者ごとに認証情報を発行します。SPLITWISE_API_KEY（またはコンシューマーキー／シークレット）を git にコミットしたり、共有チャットに貼り付けたり、公開クライアントに埋め込んだりしないでください。

5. このサーバーを Splitwise アカウントと連携して使用した結果について、全責任を負うものとします。 レート制限、API キーの取り消し、アカウントへの警告、または何らかの措置が含まれます。Splitwise があなたの使用に異議を唱えた場合、または使用量がレート制限を超えた場合は、このサーバーの使用を中止してください。

このセクションは、保守担当者が誠意をもって規約を要約したものです。法律上の助言ではなく、Splitwise の実際の Developer Terms を変更または置き換えるものでもありません。

インストール

オプション 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 key をコピーします

認証情報

環境変数	必須	備考
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：2 段階で実行されます。最初の呼び出しでは何も行われず、プレビューとトークンが返されます。モデルは、トークンを指定して再度呼び出す前に、チャットでユーザーの承認を得る必要があります。auto：同じく 2 段階で実行されますが、モデルはプレビューを自分で確認した後にトークンを使用できます。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でページ分割されます。1 行につき 1 件の支出を表示する照合ビューにはview: "rows"を、エントリーが削除された理由を確認するにはinclude_comments: trueを指定します
sw_get_expense	1 件の支出の詳細をすべて取得します（簡易表示には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	1 回のプレビューと承認で、複数の支出／コメントの書き込みを行います。後続の操作では、先行する操作で新規作成されたexpense_idを使用できます

レシート

ツール	説明
sw_get_receipt	サーバーの認証情報を使って支出のレシート画像／PDFをダウンロードします。インライン（inline）、抽出した PDF テキスト（extract_text）、および／またはファイルへの書き込みとして返します
sw_get_upload_url	ホスト版のみ：レシートファイルをcurl -X PUTでアップロードするための短期間有効な署名付き URL を返します。その後、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 } を使用できます。PNG、JPEG、GIF、PDF に対応し、上限は 10 MiB です（Splitwise のドキュメントには上限の記載がありません）。種類はバイト列から判定され、実際の種類と一致しない mime_type は拒否されます。確認プレビューには内容の代わりにファイル名、種類、サイズ、SHA-256 が表示され、トークンはそのバイト列に紐付けられます。書き込み後、ツールは Splitwise が実際にファイルを保存したこと（receipt.original）を確認し、保存されていない場合は該当する費用の名前を含むエラーを返します。レシートを添付すると、その費用にすでに添付されているレシートは置き換えられます。

レシートの URL を開くと 401 が返る -- 費用に記載されている receipt.original / receipt.large の URL は公開されておらず、API キーが必要です。URL を直接取得するのではなく、sw_get_receipt を使用してください。

レシートが読み取れない場所に保存される -- sw_get_receipt は サーバー側 のファイルシステムに書き込みます。サーバーがホストされている、またはコンテナ化されている場合、これは呼び出し元のファイルシステムとは異なります。バイト列を取得するには inline: true（画像の場合は画像ブロック、PDF の場合は埋め込みリソース）、PDF のテキストを取得するには extract_text: true を指定してください。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