splitwise-mcp 1.0.0

package/dist/client.js

@@ -0,0 +1,44 @@
+import { config as loadDotenv } from 'dotenv';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+loadDotenv({ path: join(__dirname, '..', '.env'), override: false, quiet: true });
+const BASE_URL = 'https://secure.splitwise.com/api/v3.0';
+export class SplitwiseClient {
+    apiKey;
+    constructor() {
+        const key = process.env.SPLITWISE_API_KEY;
+        if (!key)
+            throw new Error('SPLITWISE_API_KEY environment variable is required');
+        this.apiKey = key;
+    }
+    async request(method, path, body) {
+        return this.doRequest(method, path, body, false);
+    }
+    async doRequest(method, path, body, isRetry) {
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        };
+        const response = await fetch(`${BASE_URL}${path}`, {
+            method,
+            headers,
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        if (response.status === 401) {
+            throw new Error('SPLITWISE_API_KEY is invalid or missing');
+        }
+        if (response.status === 429) {
+            if (!isRetry) {
+                await new Promise((r) => setTimeout(r, 2000));
+                return this.doRequest(method, path, body, true);
+            }
+            throw new Error('Rate limited by Splitwise API');
+        }
+        if (!response.ok) {
+            throw new Error(`Splitwise API error: ${response.status} ${response.statusText} for ${method} ${path}`);
+        }
+        return response.json();
+    }
+}

package/dist/index.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema, CallToolRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { SplitwiseClient } from './client.js';
+import { toolDefinitions as userTools, handleTool as handleUser } from './tools/user.js';
+import { toolDefinitions as groupTools, handleTool as handleGroups } from './tools/groups.js';
+import { toolDefinitions as friendTools, handleTool as handleFriends } from './tools/friends.js';
+import { toolDefinitions as expenseTools, handleTool as handleExpenses } from './tools/expenses.js';
+import { toolDefinitions as utilityTools, handleTool as handleUtilities } from './tools/utilities.js';
+const client = new SplitwiseClient();
+const allTools = [
+    ...userTools,
+    ...groupTools,
+    ...friendTools,
+    ...expenseTools,
+    ...utilityTools,
+];
+const handlers = {};
+for (const tool of userTools)
+    handlers[tool.name] = (n, a) => handleUser(n, a, client);
+for (const tool of groupTools)
+    handlers[tool.name] = (n, a) => handleGroups(n, a, client);
+for (const tool of friendTools)
+    handlers[tool.name] = (n, a) => handleFriends(n, a, client);
+for (const tool of expenseTools)
+    handlers[tool.name] = (n, a) => handleExpenses(n, a, client);
+for (const tool of utilityTools)
+    handlers[tool.name] = (n, a) => handleUtilities(n, a, client);
+const server = new Server({ name: 'splitwise-mcp', version: '1.0.0' }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: allTools }));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+    const handler = handlers[name];
+    if (!handler) {
+        return {
+            content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+            isError: true,
+        };
+    }
+    try {
+        return await handler(name, args);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: 'text', text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+console.error('[splitwise-mcp] This project was developed and is maintained by AI (Claude Sonnet 4.6). Use at your own discretion.');
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/tools/expenses.js

@@ -0,0 +1,170 @@
+/** Flattens a users array into Splitwise's flat-param JSON format. */
+export function flattenUsers(users) {
+    const flat = {};
+    users.forEach((u, i) => {
+        flat[`users__${i}__user_id`] = u.user_id;
+        flat[`users__${i}__paid_share`] = u.paid_share;
+        flat[`users__${i}__owed_share`] = u.owed_share;
+    });
+    return flat;
+}
+function buildExpenseBody(args) {
+    const { split_equally, users, expense_id: _id, ...rest } = args;
+    if (split_equally && users) {
+        throw new Error('Provide either split_equally or users, not both');
+    }
+    const body = { ...rest };
+    if (split_equally) {
+        body.split_equally = true;
+    }
+    else if (users) {
+        Object.assign(body, flattenUsers(users));
+    }
+    return body;
+}
+export const toolDefinitions = [
+    {
+        name: 'sw_list_expenses',
+        description: 'List or search Splitwise expenses. All filters are optional. Use group_id to filter by group, dated_after/dated_before for date ranges.',
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                group_id: { type: 'integer', description: 'Only expenses in this group' },
+                friend_id: { type: 'integer', description: 'Only expenses with this friend' },
+                dated_after: { type: 'string', description: 'ISO 8601 date — only expenses on or after this date' },
+                dated_before: { type: 'string', description: 'ISO 8601 date — only expenses on or before this date' },
+                updated_after: { type: 'string', description: 'ISO 8601 datetime' },
+                updated_before: { type: 'string', description: 'ISO 8601 datetime' },
+                limit: { type: 'integer', description: 'Max results (API default: 20)' },
+                offset: { type: 'integer', description: 'Pagination offset' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'sw_get_expense',
+        description: 'Get full details of a single Splitwise expense by id.',
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'integer', description: 'Expense ID' },
+            },
+            required: ['id'],
+        },
+    },
+    {
+        name: 'sw_create_expense',
+        description: 'Create a Splitwise expense. Use split_equally:true to split evenly among group members, or provide a users array for custom per-person splits (paid_share and owed_share as decimal strings like "25.00"). cost must be a decimal string.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                group_id: { type: 'integer', description: 'Group to add expense to (use 0 for no group)' },
+                description: { type: 'string', description: 'Short description of the expense' },
+                cost: { type: 'string', description: 'Total cost as decimal string, e.g. "25.00"' },
+                split_equally: { type: 'boolean', description: 'Split equally among group members (mutually exclusive with users)' },
+                users: {
+                    type: 'array',
+                    description: 'Custom split (mutually exclusive with split_equally). Full list of participants required.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            user_id: { type: 'integer' },
+                            paid_share: { type: 'string', description: 'Amount this user paid, e.g. "25.00"' },
+                            owed_share: { type: 'string', description: 'Amount this user owes, e.g. "12.50"' },
+                        },
+                        required: ['user_id', 'paid_share', 'owed_share'],
+                    },
+                },
+                currency_code: { type: 'string', description: 'Currency code, e.g. "USD". Defaults to group/user default.' },
+                date: { type: 'string', description: 'ISO 8601 datetime' },
+                category_id: { type: 'integer', description: 'Category id from sw_get_categories' },
+                details: { type: 'string', description: 'Notes' },
+            },
+            required: ['group_id', 'description', 'cost'],
+        },
+    },
+    {
+        name: 'sw_update_expense',
+        description: 'Edit an existing Splitwise expense. Provide expense_id and any fields to change. For custom split updates, the full users array must be provided (the API replaces the entire split).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                expense_id: { type: 'integer', description: 'ID of the expense to update' },
+                description: { type: 'string' },
+                cost: { type: 'string', description: 'Decimal string, e.g. "25.00"' },
+                split_equally: { type: 'boolean', description: 'Mutually exclusive with users' },
+                users: {
+                    type: 'array',
+                    description: 'Full replacement split — all users must be included. Mutually exclusive with split_equally.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            user_id: { type: 'integer' },
+                            paid_share: { type: 'string' },
+                            owed_share: { type: 'string' },
+                        },
+                        required: ['user_id', 'paid_share', 'owed_share'],
+                    },
+                },
+                currency_code: { type: 'string' },
+                date: { type: 'string' },
+                category_id: { type: 'integer' },
+                details: { type: 'string' },
+            },
+            required: ['expense_id'],
+        },
+    },
+    {
+        name: 'sw_delete_expense',
+        description: 'Soft-delete a Splitwise expense by id. Returns {success: true} on success. Note: restoring deleted expenses requires sw_undelete_expense (not yet implemented).',
+        annotations: { destructiveHint: true },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'integer', description: 'Expense ID to delete' },
+            },
+            required: ['id'],
+        },
+    },
+    // TODO: sw_undelete_expense — POST /undelete_expense/{id} — restore a soft-deleted expense
+];
+export async function handleTool(name, args, client) {
+    switch (name) {
+        case 'sw_list_expenses': {
+            const params = new URLSearchParams();
+            const filters = ['group_id', 'friend_id', 'dated_after', 'dated_before', 'updated_after', 'updated_before', 'limit', 'offset'];
+            for (const key of filters) {
+                if (args[key] !== undefined)
+                    params.append(key, String(args[key]));
+            }
+            const qs = params.toString();
+            const data = await client.request('GET', qs ? `/get_expenses?${qs}` : '/get_expenses');
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        case 'sw_get_expense': {
+            const { id } = args;
+            const data = await client.request('GET', `/get_expense/${id}`);
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        case 'sw_create_expense': {
+            const body = buildExpenseBody(args);
+            const data = await client.request('POST', '/create_expense', body);
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        case 'sw_update_expense': {
+            const { expense_id } = args;
+            const body = buildExpenseBody(args);
+            const data = await client.request('POST', `/update_expense/${expense_id}`, body);
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        case 'sw_delete_expense': {
+            const { id } = args;
+            const data = await client.request('POST', `/delete_expense/${id}`);
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}

package/dist/tools/friends.js

@@ -0,0 +1,20 @@
+export const toolDefinitions = [
+    {
+        name: 'sw_list_friends',
+        description: 'List all Splitwise friends with their id, first_name, last_name, and email. Use this to resolve a friend\'s name to a user_id before adding them to a group or building a custom expense split.',
+        annotations: { readOnlyHint: true },
+        inputSchema: { type: 'object', properties: {}, required: [] },
+    },
+    // TODO: sw_create_friend — POST /create_friend — add a friend by email (user_email, user_first_name, user_last_name)
+    // TODO: sw_delete_friend — POST /delete_friend/{id} — remove a friendship
+];
+export async function handleTool(name, _args, client) {
+    switch (name) {
+        case 'sw_list_friends': {
+            const data = await client.request('GET', '/get_friends');
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}

package/dist/tools/groups.js

@@ -0,0 +1,111 @@
+export const toolDefinitions = [
+    {
+        name: 'sw_list_groups',
+        description: 'List all Splitwise groups the current user belongs to. Returns id, name, and members for each group. Use this to resolve a group name to its id.',
+        annotations: { readOnlyHint: true },
+        inputSchema: { type: 'object', properties: {}, required: [] },
+    },
+    {
+        name: 'sw_get_group',
+        description: 'Get details of a single Splitwise group including all members and balances.',
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'integer', description: 'Group ID' },
+            },
+            required: ['id'],
+        },
+    },
+    {
+        name: 'sw_create_group',
+        description: 'Create a new Splitwise group.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Group name' },
+                group_type: {
+                    type: 'string',
+                    enum: ['apartment', 'house', 'trip', 'other'],
+                    description: 'Type of group',
+                },
+                simplify_by_default: { type: 'boolean', description: 'Whether to simplify debts by default' },
+            },
+            required: ['name'],
+        },
+    },
+    {
+        name: 'sw_add_user_to_group',
+        description: 'Add a user to a Splitwise group. Provide user_id (preferred, use sw_list_friends to resolve a name) or first_name + last_name + email to invite by email.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                group_id: { type: 'integer', description: 'Group ID' },
+                user_id: { type: 'integer', description: 'User ID (preferred)' },
+                first_name: { type: 'string' },
+                last_name: { type: 'string' },
+                email: { type: 'string' },
+            },
+            required: ['group_id'],
+        },
+    },
+    {
+        name: 'sw_remove_user_from_group',
+        description: 'Remove a user from a Splitwise group.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                group_id: { type: 'integer', description: 'Group ID' },
+                user_id: { type: 'integer', description: 'User ID to remove' },
+            },
+            required: ['group_id', 'user_id'],
+        },
+    },
+    // TODO: sw_delete_group — POST /delete_group/{id} — soft-delete a group
+    // TODO: sw_undelete_group — POST /undelete_group/{id} — restore a soft-deleted group
+];
+export async function handleTool(name, args, client) {
+    switch (name) {
+        case 'sw_list_groups': {
+            const data = await client.request('GET', '/get_groups');
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        case 'sw_get_group': {
+            const { id } = args;
+            const data = await client.request('GET', `/get_group/${id}`);
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        case 'sw_create_group': {
+            const { name, group_type, simplify_by_default } = args;
+            const body = { name };
+            if (group_type !== undefined)
+                body.group_type = group_type;
+            if (simplify_by_default !== undefined)
+                body.simplify_by_default = simplify_by_default;
+            const data = await client.request('POST', '/create_group', body);
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        case 'sw_add_user_to_group': {
+            const { group_id, user_id, first_name, last_name, email } = args;
+            let body;
+            if (user_id !== undefined) {
+                body = { group_id, user_id };
+            }
+            else {
+                if (!first_name || !last_name || !email) {
+                    throw new Error('first_name, last_name, and email are required when user_id is not provided');
+                }
+                body = { group_id, first_name, last_name, email };
+            }
+            const data = await client.request('POST', '/add_user_to_group', body);
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        case 'sw_remove_user_from_group': {
+            const { group_id, user_id } = args;
+            const data = await client.request('POST', '/remove_user_from_group', { group_id, user_id });
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}

package/dist/tools/user.js

@@ -0,0 +1,20 @@
+export const toolDefinitions = [
+    {
+        name: 'sw_get_current_user',
+        description: 'Get the authenticated Splitwise user\'s profile (id, first_name, last_name, email). Use the returned id when building custom expense splits.',
+        annotations: { readOnlyHint: true },
+        inputSchema: { type: 'object', properties: {}, required: [] },
+    },
+    // TODO: sw_get_user — GET /get_user/{id} — get another user's profile by id
+    // TODO: sw_update_user — POST /update_user/{id} — update current user's profile (first_name, last_name, email, password, locale, default_currency)
+];
+export async function handleTool(name, _args, client) {
+    switch (name) {
+        case 'sw_get_current_user': {
+            const data = await client.request('GET', '/get_current_user');
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}

package/dist/tools/utilities.js

@@ -0,0 +1,41 @@
+export const toolDefinitions = [
+    {
+        name: 'sw_get_notifications',
+        description: 'Get recent Splitwise activity notifications for the current user.',
+        annotations: { readOnlyHint: true },
+        inputSchema: { type: 'object', properties: {}, required: [] },
+    },
+    {
+        name: 'sw_get_categories',
+        description: 'Get the hierarchical list of Splitwise expense categories. Use the returned id as category_id when creating expenses.',
+        annotations: { readOnlyHint: true },
+        inputSchema: { type: 'object', properties: {}, required: [] },
+    },
+    {
+        name: 'sw_get_currencies',
+        description: 'Get all Splitwise-supported currency codes and units. Use the currency_code value when creating expenses in non-default currencies.',
+        annotations: { readOnlyHint: true },
+        inputSchema: { type: 'object', properties: {}, required: [] },
+    },
+    // TODO: sw_get_comments — GET /get_comments?expense_id= — get comments on an expense
+    // TODO: sw_create_comment — POST /create_comment — add a comment to an expense (expense_id, content)
+    // TODO: sw_delete_comment — POST /delete_comment/{id} — delete a comment
+];
+export async function handleTool(name, _args, client) {
+    switch (name) {
+        case 'sw_get_notifications': {
+            const data = await client.request('GET', '/get_notifications');
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        case 'sw_get_categories': {
+            const data = await client.request('GET', '/get_categories');
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        case 'sw_get_currencies': {
+            const data = await client.request('GET', '/get_currencies');
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "splitwise-mcp",
+  "version": "1.0.0",
+  "description": "Splitwise MCP server for Claude — developed and maintained by AI (Claude Sonnet 4.6)",
+  "author": "Claude Sonnet 4.6 (AI) <https://www.anthropic.com/claude>",
+  "type": "module",
+  "bin": {
+    "splitwise-mcp": "dist/index.js"
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "dev": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "dotenv": "^17.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  }
+}