My Portfolio MCP Server

A Model Context Protocol (MCP) server for managing investment portfolios. Built with Node.js, SQLite, and Google Drive integration.

Quick Start

👉 New? See QUICKSTART.md for setup in 5 minutes

Features

• Transaction Management: Track buys, sells, and dividends
• Position Tracking: Manage open and closed positions with cost basis
• Alerts: Create and store price/gain-loss alerts
• Daily Position Snapshots: Record end-of-day portfolio snapshots
• Comments with History: Full comment history on positions and alerts
• Google Drive Sync: Automatic sync and daily backups
• MCP Integration: Use with Claude for natural language portfolio queries

Setup

Prerequisites

• Node.js 18+
• Google account with Drive access
• Railway account (for deployment)

OAuth Setup

This project uses OAuth 2.0 for Google Drive access.

For detailed setup instructions including:

• Creating OAuth credentials in Google Cloud
• Generating authorization tokens
• Creating a Google Drive folder
• Configuring environment variables

👉 See OAUTH_SETUP.md

Local Development

1. Clone and install:

npm install

2. Create .env file from .env.example:

cp .env.example .env

3. Set up OAuth (see OAUTH_SETUP.md):

   • Create OAuth credentials in Google Cloud Console
   • Authorize locally to generate tokens.json
   • Create a Google Drive folder
   • Set DRIVE_FOLDER_ID in .env

4. Build and run:

npm run build
npm start

The first run will prompt you to authorize with Google (opens browser). On subsequent runs, it uses the saved token.

Or for development with auto-reload:

npm run dev

Available Tools

Transactions

• list_transactions - Get all transactions with optional filters
• add_transaction - Create a new transaction (BUY/SELL/DIVIDEND)
• update_transaction - Modify transaction details
• delete_transaction - Remove a transaction

Positions

• list_positions - Get all positions (OPEN/CLOSED)
• add_position - Create a new position
• update_position - Update shares or average cost
• close_position - Mark position as closed
• add_position_comment - Add comment to position
• list_position_comments - Get comment history
• get_position_summary - Portfolio stats

Daily Positions

• record_daily_position - Record single EOD snapshot
• record_daily_positions_batch - Bulk insert for historical data
• list_daily_positions - Query snapshots with filters

Alerts

• list_alerts - Get all alerts
• add_alert - Create alert (PRICE_ABOVE/PRICE_BELOW/GAIN_LOSS_PERCENT)
• update_alert - Modify alert
• delete_alert - Remove alert
• add_alert_comment - Add comment to alert
• list_alert_comments - Get comment history

Utilities

• sync_portfolio_to_drive - Manual sync trigger
• get_portfolio_stats - Portfolio summary

Deployment to Railway

1. Complete OAuth setup locally first

2. Push code to git repository:

   git add .
   git commit -m "Add portfolio MCP server"
   git push origin main
   

3. Connect to Railway.app and link your GitHub repo

4. Set environment variables in Railway dashboard:

   • OAUTH_CREDENTIALS_JSON (base64-encoded, see OAUTH_SETUP.md)
   • OAUTH_TOKEN_JSON (base64-encoded, see OAUTH_SETUP.md)
   • DRIVE_FOLDER_ID
   • DATABASE_SYNC_INTERVAL_MINUTES=1 (optional, default: 1)
   • BACKUP_TIME_UTC=23:00 (optional, default: 23:00)

5. Railway will auto-build and deploy

Note: OAuth credentials and tokens are NOT stored in git (in .gitignore). They are provided via Railway environment variables. See OAUTH_SETUP.md for detailed instructions.

Data Storage

• Primary: SQLite database (portfolio_data.db)
• Backup: Synced to Google Drive every 1 minute
• Daily Backups: Timestamped backups retained for 7 days
• Files: Not encrypted by default (relies on Drive + file permissions)

Architecture

MCP Server (stdio transport)
    ↓
Tools (Transactions, Positions, Alerts, DailyPositions)
    ↓
SQLite Database (local)
    ↓
Google Drive (sync + backups)

Using with Claude

Connect this MCP server to Claude and query your portfolio:

• "What's my total cost basis?"
• "Add 100 shares of AAPL at $150"
• "Show me all OPEN positions"
• "Create an alert if TSLA goes above $250"

Configuration

Environment variables in .env:

Variable	Description	Default
NODE_ENV	Environment	development
OAUTH_CREDENTIALS_JSON	OAuth credentials (JSON or base64)	(from file)
OAUTH_TOKEN_JSON	OAuth token (JSON or base64)	(from file)
DRIVE_FOLDER_ID	Google Drive folder ID	-
DATABASE_PATH	SQLite database path	./portfolio_data.db
DATABASE_SYNC_INTERVAL_MINUTES	Sync interval	1
BACKUP_TIME_UTC	Daily backup time	23:00

See OAUTH_SETUP.md for details on OAuth variables.

Security Notes

• OAuth tokens are refresh tokens (not passwords)
• Both credential files are in .gitignore (never committed to GitHub)
• Secrets stored as env vars in Railway, encrypted by Railway
• SQLite not encrypted by default (can add SQLCipher for sensitive data)
• Backups inherit Google Drive encryption
• Use parameterized SQL queries (no injection risk)
• You can revoke access anytime in Google Account

Development

Type checking:

npm run build

License

MIT