create_expense
Create a new shared expense with explicit per-user splits in Splitwise. Specify description, cost, date, and individual payment details for accurate tracking.
Instructions
Create a new Splitwise expense with explicit per-user splits. Always confirm split details with the user before calling.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| description | Yes | Expense description e.g. "Dinner at Nobu" | |
| cost | Yes | Total cost as decimal string e.g. "42.50" | |
| date | Yes | ISO date e.g. 2025-03-15 | |
| currency_code | No | Currency code e.g. USD, EUR (default USD) | |
| group_id | No | Group ID if this is a group expense | |
| users | Yes | All involved users with their paid and owed shares |
Implementation Reference
- src/client.ts:141-157 (handler)The actual implementation of the `createExpense` method in the `SplitwiseClient` class, which handles the API request to create an expense.
async createExpense(params: CreateExpenseParams): Promise<SplitwiseExpense> { const body: Record<string, unknown> = { cost: params.cost, description: params.description, date: params.date, currency_code: params.currency_code ?? 'USD', }; if (params.group_id !== undefined) body.group_id = params.group_id; params.users.forEach((u, i) => { body[`users__${i}__user_id`] = u.user_id; body[`users__${i}__paid_share`] = u.paid_share; body[`users__${i}__owed_share`] = u.owed_share; }); const data = await this.post<{ expense: SplitwiseExpense }>('/create_expense', body); return data.expense; } - src/client.ts:59-66 (schema)Type definition for the `createExpense` parameters.
export interface CreateExpenseParams { cost: string; description: string; date: string; group_id?: number; currency_code?: string; users: Array<{ user_id: number; paid_share: string; owed_share: string }>; } - src/tools/expenses.ts:42-72 (registration)The MCP tool definition for `create_expense`, including the schema (using Zod) and the handler which calls the client's `createExpense` method.
name: 'create_expense', description: 'Create a new Splitwise expense with explicit per-user splits. Always confirm split details with the user before calling.', inputSchema: z.object({ description: z.string().describe('Expense description e.g. "Dinner at Nobu"'), cost: z.string().describe('Total cost as decimal string e.g. "42.50"'), date: z.string().describe('ISO date e.g. 2025-03-15'), currency_code: z.string().optional().describe('Currency code e.g. USD, EUR (default USD)'), group_id: z.number().int().optional().describe('Group ID if this is a group expense'), users: z .array( z.object({ user_id: z.number().int().describe('Splitwise user ID'), paid_share: z.string().describe('Amount this user paid e.g. "42.50"'), owed_share: z.string().describe('Amount this user owes e.g. "21.25"'), }), ) .min(2) .describe('All involved users with their paid and owed shares'), }), handler: async (args: { description: string; cost: string; date: string; currency_code?: string; group_id?: number; users: Array<{ user_id: number; paid_share: string; owed_share: string }>; }) => { return client.createExpense(args); }, },