open-splitwise

Splitwise をエージェントネイティブな経費トラッカーに変える。

あらゆる AI エージェント — Hermes、Claude Desktop、Claude Code、Cursor、または MCP を話せるものなら何でも — が残高を読み取り、雑然とした自然言語から経費を割り勘し、自身の認証問題を診断し、レート制限を気にする必要がない、オープンな Model Context Protocol(MCP) サーバー。

Python 3.11+ · MCP spec 2026-07-28 · stdio transport · 33 tools · lazy-loaded

なぜ

既存の Splitwise インテグレーションは、モデルに生の API ミラーを渡してうまくいくことを願うだけだ。それは予測可能な形で失敗する: モデルがカテゴリ ID をでっち上げ、₹300 を 3 人で誤って割り勘し、実際には失敗したリクエストなのに Splitwise の 200 OK を信じ、レート制限の応答を積極的に再試行すべきバグとして扱う。

open-splitwise はこれをサーバーレイヤーで修正する:

機能

• 完全な API カバレッジ — 公式 Splitwise OpenAPI 3.0 仕様の全 27 エンドポイントを、それぞれ 1 ツールとして、忠実な名前で提供。

• ワークフローレイヤー — 1 つの発話が 1 回の呼び出しに対応する高レベルツール。

• セルフサービス認証ライフサイクル — setup_auth はキーを保存する前に Splitwise に対してライブで検証する(誤ったキーは決して永続化されない)。get_auth_status は設定内容を説明し、logout は資格情報を消去する。セッション途中での再認証も機能する。

• 正直なエラー — すべての失敗モード(人物が解決できない、負担額の合計不一致、不明なカテゴリ、失効したキー、再試行の枯渇)は、何が起きたかと次に何をすべきかを正確に伝えるテキストを返す。

• デフォルト安全なアノテーション — 読み取りは readOnlyHint を、破壊的な削除は destructiveHint を、MCP 2026-07-28 セマンティクスに従って保持する。ツールはキャッシュに優しいディスカバリのため決定的な順序で登録される。

• ローカル優先のシークレット — API キーは ~/.config/splitwise-mcp/credentials.json にモード 0600 で保存され、アトミックに書き込まれ、決してエコーバックされない(マスクされたプレビューのみ)。

クイックスタート

git clone https://github.com/<you>/open-splitwise.git
cd open-splitwise
uv sync

スタンドアロンで実行(stdio):

uv run open-splitwise          # starts with no key configured — see auth below

https://secure.splitwise.com/apps で API キーを取得 (アカウント設定 → API キー)。

任意の MCP クライアントに接続

汎用 stdio ブロック(Claude Desktop の claude_desktop_config.json、Claude Code の .mcp.json、Cursor など):

{
  "mcpServers": {
    "splitwise": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/open-splitwise", "run", "open-splitwise"],
      "env": { "SPLITWISE_API_KEY": "<optional: preconfigure>" }
    }
  }
}

Hermes Agent に接続

~/.hermes/config.yaml に追加:

mcp_servers:
  splitwise:
    command: "uv"
    args: ["--directory", "/absolute/path/to/open-splitwise", "run", "open-splitwise"]
    env:
      SPLITWISE_API_KEY: "<optional>"
    tools:
      include: [quick_add_expense, resolve_users, money_summary, get_auth_status]
    prompts: false
    resources: false

その後 /reload-mcp を実行。上記の 4 つのワークフロー/認証ツールから始め、必要なときだけ生の API ツールを追加する — Hermes のサーバー単位フィルタリングによりツール面は小さく保たれる。

認証ライフサイクル

このサーバーは、エージェントが認証を自ら診断・修正し、あなたにシークレットだけを尋ねるように設計されている:

キーの解決はリクエストごとに行われる: 保存済みの資格情報 → SPLITWISE_API_KEY 環境変数 → なし。保存したばかりのキーは実行中のプロセスに即座に反映される — 再起動はゼロ。

資格情報は ~/.config/splitwise-mcp/credentials.json(モード 0600)に置かれる。ディレクトリは SPLITWISE_MCP_CONFIG_DIR で上書きできる(テストや複数プロファイル構成に便利)。

エージェントの使いやすさ

You:      "add dinner 900 split with alice and bob@x.com, groceries"
Agent:    quick_add_expense(description="Dinner", cost="900.00",
                            participants=["alice", "bob@x.com"],
                            category_name="groceries")
Server:   resolves alice→12? two matches! → error listing Alice A (id 10), Alice Wood (id 12)
Agent:    "Which Alice?"  → you answer → re-call succeeds
Server:   { status: created, expense_id: 99123,
            splits: [ "Nikhil paid 900.00 INR",
                      "Alice A owes 300.00 INR",
                      "Bob B owes 300.00 INR" ] }

• quick_add_expense — 名前/部分名/メールアドレス/ID を受け付ける。均等割りは余りのセントを決定的に分配して計算。カスタム owed_shares は合計が正確になるよう検証。支払い者はデフォルトで含まれる(消費していない場合は include_payer_in_split=false)。通貨はプロフィールからデフォルト設定。

• resolve_users — メール完全一致、フルネーム一致、一意のファーストネーム、部分文字列フォールバック。曖昧な場合は推測せず候補を返す。

• money_summary — 通貨ごとの owed_to_you / you_owe / net、フレンドレベルの残高、自分が関わるグループの簡易債務。

ツールリファレンス(33)

* は destructiveHint=true でアノテーション済み。すべての get_* ツールは readOnlyHint=true でアノテーション済み。両方が存在する場合は、生のツールよりワークフローツールを優先すること。

レート制限

Splitwise はスロットリング時に HTTP 429 を返す。open-splitwise は自動的に再試行する: Retry-After ヘッダーをそのまま尊重し、それ以外は指数バックオフ(0.5 秒から倍増、最大 30 秒)で、デフォルトで最大 3 回試行する。エージェントがエラーを見るのは全試行を使い果たした場合のみ — そのエラーは盲目的な再試行ではなくペースを落とすよう指示する。

設定

Splitwise の癖を吸収

• 配列パラメータを Splitwise の変則的な users__{index}__{property} エンコーディングにフラット化

• 200 OK ≠ 成功: すべての変更操作で errors{} / success:false を検査

• 金額は小数 2 桁の 10 進文字列。余りのセントは分配され、合計は常に正確

• category_id はサブカテゴリである必要がある — ファジーな名前解決で強制

• 残高/債務は事前計算済みの balance[] / simplified_debts から読み取る(再計算はしない)

• 「精算」は payment:true の経費にすぎない(専用エンドポイントは存在しない)

• OAuth2 は存在するが意図的にスコープ外: 個人用 API キーがエージェントがユーザーに尋ねるフローに適合。OAuth はリダイレクト URI + ブラウザが必要(ホスト型デプロイのみ)

アーキテクチャ

┌─────────────── any MCP client ───────────────┐
│  Hermes / Claude Desktop / Cursor / …        │
└──────────────────┬───────────────────────────┘
                   │ JSON-RPC over stdio
┌──────────────────▼───────────────────────────┐
│ server.py — FastMCP app, 33 tools            │
│   workflows · raw endpoints · auth lifecycle │
├──────────────────────────────────────────────┤
│ client.py — async REST client                │
│   bearer auth (per-request key resolution)   │
│   param flattening · success verification    │
│   transparent 429 retry/backoff              │
├──────────────────────────────────────────────┤
│ auth.py — credentials.json (0600, atomic)    │
└──────────────────┬───────────────────────────┘
                   │ HTTPS
          secure.splitwise.com/api/v3.0

開発

uv run pytest                        # 54 tests: client, rate limits, auth, workflows, lazy loading, MCP semantics
uv run python scripts/smoke_stdio.py # real subprocess: handshake, discovery, live auth-failure paths

テストファースト(厳格な TDD)で構築: 上記のすべての動作は、最初に失敗するテストから始まる由来を持つ。構成:

src/open_splitwise/
  client.py    # REST client: auth provider, flattening, retry, error mapping
  auth.py      # credential storage
  server.py    # FastMCP definitions: workflows + raw + auth tools
tests/
scripts/smoke_stdio.py

利用規約

Splitwise のセルフサービス API は、同社の API 利用規約により非商用である。あなたの API キーはアカウントへの完全なアクセスを許可する — パスワードのように扱うこと。このプロジェクトは独立したインテグレーションであり、Splitwise Inc. とは提携しておらず、同社の承認も受けていない。

ロードマップ

• 経費作成時のレシートアップロード

• 換算対応の複数通貨経費ヘルパー

• MCP プロンプトとしての定期経費サマリー

• ホスト型/マルチユーザーデプロイ向けのオプションの Streamable HTTP トランスポート(+OAuth2)

• PyPI への公開(uvx open-splitwise)

コントリビューション

PR 歓迎 — TDD の規律(テストが最初に失敗し、その後成功する)を守り、ツールの説明はモデル向けに書き、シークレットをログに記録しないこと。

ライセンス

MIT — すべての人に開かれている: 使うも、改変するも、出荷するも、販売するも自由。著作権表示だけは保持すること。