Skip to main content
Glama
deenesjakoruzh
nnishad

open-splitwise

by nnishad
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

open-splitwise

将 Splitwise 变成智能体原生的费用追踪器。

一个开源的 Model Context Protocol（MCP）服务器，让任何 AI 智能体——Hermes、Claude Desktop、Claude Code、Cursor，或任何支持 MCP 的工具——都能读取余额、从杂乱的自然语言中拆分费用、自行诊断认证问题，并且永远不必担心速率限制。

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

为什么

现有的 Splitwise 集成只是把原始 API 镜像交给模型，然后寄希望于一切顺利。这会在可预见的方式上失败：模型凭空编造类别 ID、把 ₹300 错误地分成三份、在请求实际失败时却相信 Splitwise 返回的 200 OK，或者把限流响应当作需要激进重试的 bug。

open-splitwise 在服务器层解决了这些问题：

智能体面临的问题

open-splitwise 的做法

"把晚餐和 Alice 分摊"需要 3–4 次 API 调用 + 算术

quick_add_expense 将名字解析为 ID、计算精确到分的份额、选择类别、一次提交

好友列表中有两个 Alice

resolve_users 返回候选列表，让智能体询问你选哪一个

"我欠多少？"需要跨多个端点的聚合

money_summary 一次调用返回按货币计的总计

Splitwise 返回带 errors 对象的 200 OK

服务器会检查；失败以带可操作文本的工具错误形式呈现——绝无虚假成功

HTTP 429 限流

静默重试（遵循 Retry-After，回退为指数退避）

密钥被吊销 / 会话中途登出

错误会告知智能体原因并让其运行 setup_auth；新密钥立即生效，无需重启

33 个工具模式每次提示消耗约 4k token

惰性工具发现：默认只暴露 7 个核心工具；search_tools("expenses") 按需加载其余工具及其完整模式

功能特性

  • 完整的 API 覆盖——官方 Splitwise OpenAPI 3.0 规范的全部 27 个端点，每个对应一个工具，名称忠实还原。

  • 工作流层——高层工具，让一句自然语言对应一次调用。

  • 自助认证生命周期——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。从上面的四个工作流/认证工具开始；仅在需要时添加原始 API 工具——Hermes 的按服务器过滤机制让工具面保持精简。

认证生命周期

该服务器的设计目标是让智能体自行诊断和修复认证问题，只向你索要密钥：

场景

智能体可见的行为

任何地方都没有密钥

每个工具都会失败并提示："未配置 Splitwise API 密钥。请让用户在 secure.splitwise.com/apps 生成一个，然后调用 setup_auth。"

用户提供密钥

setup_auth(api_key) 首先探测 /get_current_user——无效密钥会被拒绝，不会存储；有效密钥会被保存并报告其归属

密钥被吊销 / 账户登出（HTTP 401/403）

工具失败并提示 "密钥可能已被吊销、过期，或账户已登出……请向用户索要新密钥并调用 setup_auth"

诊断

get_auth_status() → {configured, source: stored|environment, masked_key}

切换账户

logout() 删除已存储的凭据

密钥解析按请求进行：已存储的凭据 → 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 个）

分组

工具

工作流

quick_add_expense · resolve_users · money_summary

用户

get_current_user · get_user · update_user

群组

get_groups · get_group · create_group · delete_group* · undelete_group · add_user_to_group · remove_user_from_group

好友

get_friends · get_friend · create_friend · create_friends · delete_friend*

费用

get_expenses · get_expense · create_expense · update_expense · delete_expense* · undelete_expense

评论

get_comments · create_comment · delete_comment*

通知

get_notifications

其他

get_currencies · get_categories

认证

setup_auth · get_auth_status · logout*

* 标注了 destructiveHint=true；所有 get_* 工具标注了 readOnlyHint=true。当两者同时存在时，优先使用工作流工具而非原始工具。

限流

Splitwise 在限流时返回 HTTP 429。open-splitwise 会自动重试：严格遵循 Retry-After 头；否则采用指数退避（0.5 秒起翻倍，上限 30 秒），默认最多重试 3 次。只有所有尝试都耗尽时智能体才会看到错误——而且该错误会提示放慢速度，而不是盲目重试。

配置

环境变量

默认值

用途

SPLITWISE_API_KEY

–

引导密钥（已存储的凭据优先）

SPLITWISE_MCP_CONFIG_DIR

~/.config/splitwise-mcp

credentials.json 的存放位置

SPLITWISE_MCP_MAX_RETRIES

3

在报错前对 429 的重试次数

SPLITWISE_MCP_LAZY

on

off 时预先注册全部 33 个工具

已为你处理的 Splitwise 怪癖

  • 数组参数被扁平化为 Splitwise 奇怪的 users__{index}__{property} 编码

  • 200 OK ≠ 成功：每次变更操作都会检查 errors{} / success:false

  • 金额以带 2 位小数的十进制字符串表示；余数分被分配，总和始终精确

  • 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——对所有人开放：使用、修改、发布、商用皆可。只需保留版权声明。

This server cannot be installed

-
license - not tested
Not graded
quality - not tested
C
maintenance

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

  • BankSync

    Connect AI agents to bank accounts, transactions, balances, and investments.

  • Ledgy

    Log, query, and edit expenses, budgets, and accounts in Ledgy from any MCP-compatible AI assistant.

  • Market Intel MCP

    Live & historical FX rates and currency conversion for AI agents. No API keys.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/nnishad/open-splitwise-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server