Tiller Money MCP Server

A Model Context Protocol (MCP) server for Tiller Money's Google Sheets-based personal finance tracking. Enables natural language queries against your financial data through Claude Desktop with direct read-only access via the Google Sheets API and OAuth2 authentication.

Quick Start

1. Installation

1. Clone this repository:

   git clone https://github.com/jackstein21/tiller-mcp-server.git
   cd tiller_mcp
   

2. Set up Python environment:

   # Using conda (recommended)
   conda create -n tiller_mcp python=3.12
   conda activate tiller_mcp
   
   # Install dependencies
   pip install -r requirements.txt
   

3. Set up Google Cloud Project:

   Before authenticating, you need to create a Google Cloud Project and enable the Google Sheets API:

   • Go to Google Cloud Console
   • Create a new project (or select an existing one)
   • Enable the Google Sheets API for your project
   • Create OAuth 2.0 credentials (Desktop app type)
   • Download the credentials JSON file
   • Save it as auth/credentials.json in this project

4. Authenticate with Google Sheets:

   # Run the authentication setup script
   python auth/auth_setup.py
   

   Follow the prompts:

   • Your browser will open for Google OAuth consent
   • Grant access to Google Sheets
   • Authentication token will be saved to auth/token.json

5. Configure Claude Desktop: Add this to your Claude Desktop configuration file:

   macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   Windows: %APPDATA%\Claude\claude_desktop_config.json

   {
     "mcpServers": {
       "Tiller Money": {
         "command": "/opt/anaconda3/envs/tiller_mcp/bin/python",
         "args": [
           "/path/to/your/tiller_mcp/src/tiller_mcp_server/server.py"
         ],
         "env": {
           "TILLER_SHEET_ID": "your_tiller_spreadsheet_id_here"
         }
       }
     }
   }
   

   Important:

   • Replace /path/to/your/tiller_mcp with your actual project path
   • Replace your_tiller_spreadsheet_id_here with your Tiller spreadsheet ID
   • If not using conda, update the command path to your Python interpreter

6. Get your Tiller Spreadsheet ID:

   • Open your Tiller spreadsheet in Google Sheets
   • Copy the ID from the URL: https://docs.google.com/spreadsheets/d/{SPREADSHEET_ID}/edit

7. Restart Claude Desktop

Features

Account Management

• View all active financial accounts
• Filter by account type (Credit Cards, Retirement, Savings, etc.)

Transaction Queries

• Search and filter transactions with powerful query options
• Date range filtering (start/end date)
• Account filtering (partial matching by account number)
• Category filtering (partial matching, case-insensitive)
• Amount filtering (min/max amounts for expenses or income)
• Description search across transaction text
• Pagination for large result sets
• Chronological sorting (most recent first)
• Detailed transaction lookup by ID

Category Management

• View all category definitions from Tiller
• Filter by category type (Expense, Income, Transfer)
• Filter by category group (Living, Fun, etc.)
• Optional monthly budget allocation data per category

Budget Analysis

• Access monthly budget allocations from Categories sheet
• Compare budgeted vs. actual spending
• Analyze any month or date range
• Natural language budget queries

Available Tools

Accounts

Transactions

... View full README on GitHub