Expense Tracker MCP Server

A Model Context Protocol (MCP) server for tracking business trip expenses and calculating settlement amounts using Google Sheets.

Overview

This server provides tools to:

• Create Google Sheets for expense tracking
• Parse expenses from natural language input
• Track who paid what and calculate who owes whom
• Support multiple participants and settlement calculations

Prerequisites

• Node.js 18+
• Google Cloud project with Sheets API enabled
• Google OAuth 2.0 credentials (or Service Account)

Installation

npm install
npm run build
npm test  # Verify all 18 tests pass

Setup

Option 1: Google OAuth 2.0 (Recommended for Small Projects)

1. Create a Google Cloud project and enable Sheets + Drive APIs
2. Create OAuth 2.0 credentials (Desktop application)
3. Copy .env.example to .env and add your credentials:

   GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
   GOOGLE_CLIENT_SECRET=your-client-secret
   GOOGLE_REDIRECT_URI=http://localhost:3000/oauth/callback
   DEFAULT_PARTICIPANTS=Mike,Chris
   DEFAULT_CURRENCY=MXN
   

4. Complete OAuth authorization to get refresh token:

   npm run build
   node get-refresh-token.js
   

5. Copy the generated GOOGLE_REFRESH_TOKEN to your .env

Option 2: Service Account (Better for Production)

1. Create a Service Account in Google Cloud Console
2. Download the JSON key file
3. Update configuration to use Service Account credentials

Configuration

Create a .env file from .env.example with:

• Google OAuth credentials
• Default participants list
• Preferred currency

Tools

1. create-expense-sheet - Create a new expense tracking spreadsheet
2. add-expense - Add a single expense entry
3. add-expenses-bulk - Parse and add multiple expenses
4. get-expenses - Query expenses with filters
5. get-settlement-summary - Calculate final settlement

Using with Claude

Add to your Claude Desktop config (~/.config/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "expense-tracker": {
      "command": "node",
      "args": ["/path/to/expense-tracker-mcp/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-secret",
        "GOOGLE_REDIRECT_URI": "http://localhost:3000/oauth/callback",
        "GOOGLE_REFRESH_TOKEN": "your-refresh-token",
        "DEFAULT_PARTICIPANTS": "Mike,Chris",
        "DEFAULT_CURRENCY": "MXN"
      }
    }
  }
}

Development

npm run watch     # Watch TypeScript compilation
npm run dev       # Build and start server
npm test          # Run all tests (18 tests)
npm start         # Start the server

Architecture

• src/index.ts - MCP server entry point and tool handlers
• src/config.ts - Environment configuration with Zod validation
• src/types.ts - TypeScript type definitions
• src/google/ - Google Sheets API integration
  • auth.ts - OAuth 2.0 authentication
  • client.ts - Sheets API client
  • types.ts - Google API types
• src/utils/ - Utility functions
  • parsers.ts - Natural language expense parsing
  • settlement.ts - Settlement calculation logic
  • formatters.ts - Output formatting

Security Notes

• Never commit .env file - it contains credentials
• Never expose refresh tokens in code or logs
• Use environment variables for all sensitive data
• Consider Service Account for production deployments

Testing

All functionality is tested with 18 comprehensive tests:

npm test

License

MIT