# 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

```bash
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:
   ```bash
   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`):

```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

```bash
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:

```bash
npm test
```

## License

MIT