tiller

This MCP server exposes Tiller Money data from a Google Sheets-based ledger to Claude Desktop via the MCP protocol. It provides read-only access to your accounts, transactions, categories, and budget data sourced from your Google Sheets setup. You can ask Claude natural language questions and use the available tools to fetch filtered lists of accounts, query transactions with date ranges, amounts, and descriptions, and inspect category definitions along with their monthly budgets. The server communicates with Google Sheets through an OAuth2-authenticated API, ensuring your data is retrieved securely without modification rights. To use it, configure Claude Desktop to point at the local Python server and supply your Google Sheets spreadsheet ID via the environment variable in the MCP configuration.

Prerequisites

• Python 3.12 (recommended via conda) or a compatible Python environment
• Access to the internet to install Python dependencies
• Google Cloud project with Google Sheets API enabled and OAuth 2.0 credentials (Desktop app)
• A Google service account or OAuth flow to authorize Sheets access (as described in the repository's setup steps)

Step-by-step installation

1. Clone the repository and navigate to it

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

2. Create and activate the Python environment (conda recommended)

conda create -n tiller_mcp python=3.12
conda activate tiller_mcp

3. Install dependencies

pip install -r requirements.txt

4. Set up Google Sheets authentication

• Create or select a Google Cloud Project and enable the Google Sheets API
• Create OAuth 2.0 credentials (Desktop app type)
• Download the credentials.json and save it as auth/credentials.json in the project
• Run the authentication setup script to generate a token

python auth/auth_setup.py

Follow the prompts to authorize access; the token will be saved to auth/token.json

5. Configure Claude Desktop to use the server (see next section for exact env var and path)

6. Prepare the environment variable with your Tiller spreadsheet ID (as shown in the repository’s configuration example)

export TILLER_SHEET_ID=your_tiller_spreadsheet_id_here

7. Start using the MCP server by ensuring the path to the server is correct in your MCP config and that Claude Desktop is pointed at the local server

Tips and common issues:

• Ensure you have the correct Google Sheets spreadsheetId and that the Sheets API is enabled for your project.
• The MCP server only reads data from Google Sheets; no write operations are performed.
• If Claude Desktop cannot connect, verify that the Python process is running and that the mcp_config specifies the correct command, path, and environment variable (TILLER_SHEET_ID).
• For macOS users configuring Claude Desktop, place the Python command and script path in claude_desktop_config.json as shown in the README; for Windows, use the equivalent paths in %APPDATA%.
• If you update your spreadsheet, changes will be reflected the next time you query through Claude; there is no caching beyond what the API layer uses.
• You may want to set a dedicated virtual environment or conda environment name to avoid conflicts with other Python projects.