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

Related MCP server: Trackor

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