AI导哈

Splitwise集成服务

一个轻量级的Model Context Protocol (MCP)服务器，提供Splitwise集成工具，用于管理用户、群组、朋友、费用和通知。

  • by HiFinance-pvt
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 HiFi-mcp/splitwise-mcp

使用说明

拆分MCP服务器🪙🤝

一个轻量级的模型上下文协议（MCP）服务器，提供Splitwise集成和工具，用于管理用户、组、朋友、费用和通知。此项目使用持久对象为Cloudflare Workers构建，并公开OAuth端点以授权Splitwise访问。

🚀 已部署服务器

实时URL: https://splitwise-mcp.hifi.click

  • MCP端点: https://splitwise-mcp.hifi.click/sse
  • OAuth授权: https://splitwise-mcp.hifi.click/authorize

💡 准备使用：服务器已部署并准备好与Claude Desktop、Cursor或任何兼容MCP的客户端集成。

目录

关于

Splitwise MCP是一种MCP服务器实现，旨在充当MCP客户端（如代理）和Splitwise API之间的桥梁。它公开了一组MCP工具来执行创建费用、管理组和检索通知等操作。此存储库使用Cloudflare Workers（Wrangler）、Durable Objects和Splitwise的小型OAuth提供程序。

特性✨

  • 用于有状态服务器行为的持久基于对象的MCP代理（MyMCP）
  • Splitwise集成的OAuth端点
  • 一套丰富的MCP工具，用于用户、群组、朋友、费用和通知管理
  • TypeScript、用于格式化/linting的Biome和用于本地开发和部署的Wrangler

🚨 部署第一个建议：此项目旨在从公共部署的MCP服务器用于实际集成（Claude、Cursor、代理）。仅将本地（wrangler-dev）用于开发和测试。下面的README侧重于部署的服务器工作流。

快速开始🚀

先决条件

  • Node.js（推荐16+）
  • pnpm（因为这个仓库包含一个pnpm-lock.yaml）或npm/yarn
  • 牧马人（Cloudflare CLI）

安装

# Clone the repository
git clone <your-repo-url>
cd splitwise-mcp-server

# Install dependencies
pnpm install

有用的脚本

来自package.json：

  • pnpm dev --在本地运行wrangler-dev
  • pnpm start --别名为wrangler-dev
  • pnpm deploy --运行wrangler-deploy以发布到Cloudflare

本地运行（开发）

pnpm dev
# or
pnpm start

部署到Cloudflare

pnpm deploy

环境和配置🔐

服务器需要几个环境变量（将这些设置为Wrangler secrets或在Cloudflare环境中）：

  • SPLITWISE_CONSUMER_KEY -拆分API消费者密钥
  • SPLITWISE_CONSUMER_SECRET -拆分API消费者机密
  • SPLITWISE_CALLBACK_URL --Splitwise的OAuth回调URL
  • BACKEND_URL --服务器使用的可选后端URL
  • PHONE_NUMBER --验证工具使用的电话号码（可选地用+格式化）

与牧马人一起设定秘密

wrangler secret put SPLITWISE_CONSUMER_KEY
wrangler secret put SPLITWISE_CONSUMER_SECRET
wrangler secret put SPLITWISE_CALLBACK_URL

持久对象绑定

Durable Object类是 MyMCP和in wrangler.jsonc 一个名为的绑定 MCP_OBJECT 定义。Wrangler将在您运行本地开发和部署时使用它。

地方发展

运行开发服务器：

pnpm dev

服务器将在以下时间可用 http://127.0.0.1:8787 （或Wrangler显示的URL）。

端点和OAuth流🔁

此项目使用以下路由装载OAuth提供程序和MCP API处理程序（如中所配置 src/index.ts):

  • POST /sse -MCP API处理程序（服务器通过 MyMCP.mount("/sse"))-MCP流量的主要API端点
  • GET /authorize --使用Splitwise启动OAuth授权
  • POST /register --客户端注册端点
  • POST /token --用于交换授权授予的令牌端点

备注：OAuth流是交互式的，通常从访问 /authorize 浏览器中的URL。

可用的MCP工具🧰

MCP服务器注册了许多与Splitwise交互的工具。关键因素包括：

服务器工具

  • about --返回包裹/关于信息
  • validate --基本服务器验证（返回电话号码格式）

用户工具

  • splitwise_get_current_user
  • splitwise_update_user

组工具

  • splitwise_get_groups
  • splitwise_get_group
  • splitwise_create_group
  • splitwise_delete_group
  • splitwise_undelete_group
  • splitwise_add_user_to_group
  • splitwise_remove_user_from_group

好友工具

  • splitwise_get_friends
  • splitwise_get_friend

支出工具

  • splitwise_get_expense
  • splitwise_get_expenses
  • splitwise_create_expense
  • splitwise_update_expense
  • splitwise_delete_expense
  • splitwise_undelete_expense

通知工具

  • splitwise_get_notifications
  • splitwise_check_auth

每个工具都包括通过zod进行的输入验证（参见 src/index.ts 用于参数形状）。

MCP检验员——测试与开发🧩

测试和与部署的MCP服务器交互的最简单方法是使用官方的MCP检查器工具。这提供了一个基于网络的界面来探索和测试所有可用的MCP工具。

MCP检查器快速入门

  1. 确保您的服务器已部署且可访问

    pnpm deploy
# Note your deployed URL: https://your-deployed-url.workers.dev

  2. 启动MCP检查器

    # Using pnpx (recommended)
pnpx @modelcontextprotocol/inspector@latest

# Or using npx
npx @modelcontextprotocol/inspector@latest

# Or using bunx
bunx @modelcontextprotocol/inspector@latest

  3. 连接到您的MCP服务器

    • 检查器将在您的浏览器中打开
    • 请输入您的服务器URL： https://your-deployed-url.workers.dev/sse
    • 检查员将自动发现所有可用工具

  4. 测试OAuth流

    • 首次访问 https://your-deployed-url.workers.dev/authorize 完成Splitwise OAuth
    • 然后返回检查员处测试经过身份验证的工具

Inspector中的可用工具

连接后，您将看到所有可用的工具，包括：

察看连接信息

  • about --获取服务器信息和版本
  • validate --测试服务器连接

用户管理

  • splitwise_get_current_user --获取经过身份验证的用户详细信息
  • splitwise_update_user --更新用户信息

组管理

  • splitwise_get_groups --列出所有组
  • splitwise_create_group --创建新组
  • splitwise_add_user_to_group --将成员添加到组

费用跟踪

  • splitwise_create_expense --创建新支出
  • splitwise_get_expenses --用过滤器列出费用
  • splitwise_update_expense --修改现有费用

认证

  • splitwise_check_auth --验证身份验证状态

检查员福利

✅ 可视化接口 --无需手动处理JSON请求
✅ 架构验证 --内置参数验证和提示
✅ 实时测试 --对工具响应的即时反馈
✅ 工具发现 --自动列出所有可用工具
✅ 调试错误 --清除错误消息和堆栈跟踪

工作流示例

  1. 启动检查器： pnpx @modelcontextprotocol/inspector@latest
  2. 连接到： https://your-deployed-url.workers.dev/sse
  3. 测试连接 about 工具
  4. 在以下位置完成OAuth /authorize 端点
  5. 测试经过身份验证的工具，如 splitwise_get_current_user
  6. 创建费用、管理组等。

用于生产集成

使用检查器进行测试后，使用部署的服务器：

克劳德桌面

{
	"mcpServers": {
		"splitwise": {
			"command": "node",
			"args": [
				"path/to/mcp-client.js",
				"https://your-deployed-url.workers.dev/sse"
			]
		}
	}
}

游标或其他MCP客户端

  • 配置MCP服务器URL: https://your-deployed-url.workers.dev/sse
  • 客户端将自动发现并使用可用工具

自定义应用程序

import { Client } from "@modelcontextprotocol/sdk/client/index.js";

const client = new Client({
	name: "your-app",
	version: "1.0.0",
});

// Connect to your deployed server
await client.connect("https://your-deployed-url.workers.dev/sse");

💡 专业提示：在与其他客户端集成之前，始终先使用MCP Inspector测试您的工具。这是调试问题和了解工具行为的最快方法。

使用示例📝

创建支出

{
	"tool": "splitwise_create_expense",
	"input": {
		"cost": "20.00",
		"description": "Dinner at restaurant",
		"users": [
			{ "user_id": 123, "paid_share": "10.00", "owed_share": "10.00" },
			{ "user_id": 456, "paid_share": "10.00", "owed_share": "10.00" }
		]
	}
}

获取当前用户信息

{
	"tool": "splitwise_get_current_user",
	"input": {}
}

创建组

{
	"tool": "splitwise_create_group",
	"input": {
		"name": "Weekend Trip",
		"type": "trip"
	}
}

使用过滤器获取费用

{
	"tool": "splitwise_get_expenses",
	"input": {
		"group_id": 123,
		"limit": 10,
		"dated_after": "2024-01-01"
	}
}

安全🔒

  • 所有Splitwise API调用都使用OAuth 2.0
  • 秘密存储为Wrangler/Cloudflare环境变量
  • Redis连接使用经过身份验证的令牌
  • 生产中没有记录敏感数据

故障排除🔧

OAuth重定向问题

  • 确保 SPLITWISE_CALLBACK_URL 与Splitwise应用程序中配置的完全匹配
  • 验证回调URL是否可公开访问

Redis连接错误

  • 验证 REDIS_URL 和 REDIS_TOKEN 是正确的
  • 检查Redis实例是否可以从Cloudflare Workers访问

MCP工具身份验证

  • 大多数工具都需要有效的经过身份验证的用户会话
  • 使用 splitwise_check_auth 验证身份验证状态的工具
  • 在以下位置完成OAuth流程 /authorize 端点（如果未通过身份验证）

速率限制

  • 服务器遵守Splitwise API速率限制
  • 如果遇到速率限制，服务器将返回相应的错误消息
  • 考虑使用指数回退实现客户端重试逻辑

互动示例🧪

  1. 启动本地开发服务器并在浏览器中打开授权URL以运行OAuth流：

    pnpm dev
# then open http://127.0.0.1:8787/authorize (or the URL shown by Wrangler)

  2. 通过MCP客户端使用about工具检查服务器是否处于活动状态 （需要MCP客户或代理）。服务器将返回一个关于有效载荷的JSON。如果您需要手动测试工具，请咨询您使用的MCP客户端（此仓库提供服务器端）。工具需要有效的经过身份验证的用户道具才能执行许多操作。

部署MCP服务器——集成首选✅

您已经部署了MCP服务器——太好了。将部署的实例用作托管LLM平台（Claude、Cursor）、外部代理和任何生产工作流的主要集成目标。

部署服务器的优势

  • 适用于OAuth重定向和平台集成的公共、稳定的URL
  • 持久对象和Redis的行为类似于生产环境（没有本地环境差距）
  • 更容易与队友或第三方LLM平台共享，而不会暴露您的机器

典型部署URL： https://<your-deployed-subdomain>.workers.dev （或您的自定义域）。MCP API安装在 /sseOAuth端点仍位于 /authorize, /token，以及 /register.

快速检查（关于工具部署）

curl -X POST "https://your-deployed-url.workers.dev/sse" \
  -H "Content-Type: application/json" \
  -d '{"tool":"about","input":{}}'

如果您与托管的LLM平台集成，请将其工具/插件/拦截器配置指向已部署的 /sse 端点或使用小型代理适配器来调整请求信封。如果返回错误，请咨询您的MCP客户端以获取确切的请求信封。目标是达到部署 /sse 端点具有客户端期望的工具调用。

贡献🤝

欢迎捐款。请遵循以下小指南：

  • 分叉回购并打开PR
  • 提交前运行格式化和linting： pnpm format 和 pnpm lint:fix
  • 确保TypeScript类型检查通过： pnpm type-check

建议的低风险改进

  • 为SplitwiseAuthService包装器添加单元测试
  • 添加CI以运行 pnpm type-check, pnpm format --check 和 pnpm lint

相关 MCP