Splitwise Analyzer

This project creates a MCP server for Splitwise data analysis.

Data

Initially, the project relied on making real-time API calls to the Splitwise service, which led to high latency, even for simple LLM queries.

To address this, the architecture was updated to first sync all Splitwise data into a local SQLite database. The MCP server then operates directly on this local data source. Since Splitwise data changes infrequently and is mostly append-only, this approach significantly improves performance and was a fair tradeoff.

Below is the database schema, designed for efficient SQL queries and fast analysis:

You can explore the interactive schema visualization here: dbdiagram.io/d/68ce74db960f6d821a04188b

Features

• Data Sync: Fetches groups, friends, and expenses data from Splitwise API
• Local Storage: Stores data in a normalized SQLite database for fast queries
• MCP Server: Provides standardized tools for AI-powered data analysis
• Modular Architecture: Clean, extensible codebase with separate tool modules
• Rich Analysis: Pre-built tools for spending trends, category analysis, and custom SQL queries

Setup

1. Install Dependencies

bundle install

2. Get Splitwise API Key

1. Go to Splitwise Apps
2. Click "Register your application"
3. Copy the API key provided

3. Set Environment Variable

export SPLITWISE_API_KEY='api_key'

4. Sync Splitwise Data

ruby sync.rb

This will:

• Fetch all your Splitwise data (users, groups, friends, expenses)
• Store it in a local SQLite database (splitwise_data.db)

5. Configure MCP Client

Add to your Claude Desktop config.

Check this to know the location for the OS you are using.

For Mac: ~/Library/Application\ Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "splitwise-analyzer": {
      "command": "ruby",
      "args": ["/path/to/your/project/src/mcp_server.rb"],
      "env": {
        "SPLITWISE_DB_PATH": "/path/to/your/project/splitwise_data.db"
      }
    }
  }
}

Available Tools

The MCP server provides these analysis tools:

1. total_spending

Comprehensive spending analysis with breakdowns

• Total amounts, expense counts, averages
• Optional date range filtering
• Currency-specific analysis

2. monthly_spending_trends

Track spending patterns over time

• Monthly aggregations with trends
• Year-specific filtering available
• Expense counts and averages per month

3. category_spending_trends

Category-specific spending analysis over time

• Monthly trends for specific expense categories
• Compare spending patterns across categories
• Track category usage over time

4. execute_sql

Execute custom SQL queries against your Splitwise database so that the LLM can get the data that's not available via the above analysis tools.

• Supports complex analysis and data exploration
• Safety limited to SELECT statements only
• Configurable row limits

5. get_database_schema

Get complete database structure and example queries (mostly to support the execute_sql tool).

• Table definitions with column types
• Row counts for each table
• Pre-written example queries to get started

Usage Examples

Once configured, ask Claude to analyze your spending data:

• "What's my total spending this year?"
• "Show me spending trends by month"
• "Which categories do I spend the most on?"
• "How much have I spent on food this quarter?"
• "What's my spending pattern in different groups?"

Example Analysis

Here's a real example of the kind of analysis you can get. When asked:

"Let's compare my expenses month by month for the year 2024. Show me the spending trends and what categories I spent most on"

Claude provided a comprehensive analysis with visualizations:

In the text response, Claude provided actionable insights about spending habits, comparing different periods and identifying areas for potential optimization.

Development

Adding New Tools

1. Create a new tool class extending BaseTool:

class MyNewTool < BaseTool
  def self.tool_definition
    # Define MCP tool schema
  end

  def execute(arguments)
    # Implement tool logic
  end
end

2. Add the tool to ToolRegistry::TOOLS array
3. The tool will be automatically available through the MCP server

Troubleshooting

Common Issues

1. "No such file or directory": Ensure you've run ruby sync.rb first to create the database
2. "Permission denied": Check file permissions on the database file
3. "API key invalid": Verify your Splitwise API key is set correctly
4. MCP connection issues: Check the Claude Desktop config file path and syntax