WealthGuard MCP

About The Project

WealthGuard is an MCP server that lets you manage your personal finances through conversation. Ask Claude to analyze your monthly expenses, check budget overruns, forecast savings, or log a new transaction — all backed by a real Google Spreadsheet you own.

Available tools:

A live finance://summary/current MCP resource also lets the assistant read the current month at any time.

Built With

Getting Started

Prerequisites

• Python 3.11+

• uv package manager

• A Google Cloud Service Account with a JSON credentials file

• A Google Sheets file shared with the service account (Editor access)

Installation

1. Clone the repo

   git clone https://github.com/DoganayBalaban/finance-mcp.git
   cd finance-mcp

2. Create and activate a virtual environment

   uv venv
   source .venv/bin/activate

3. Install dependencies

   uv pip install -e .

4. Place your Service Account JSON at credentials/service_account.json

5. Copy .env.example to .env and fill in your values

   GOOGLE_SHEETS_ID="your_spreadsheet_id_here"
   SERVICE_ACCOUNT_JSON="credentials/service_account.json"

6. Create a Google Sheets file with these three worksheets:

   Worksheet	Columns
   Transactions	date, description, category, amount, type
   Budgets	category, monthly_limit, year, month
   Goals	year, month, target_amount

Usage

Claude Desktop Integration

Add the following to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "finance-mcp": {
      "command": "/FULL/PATH/finance-mcp/.venv/bin/python",
      "args": ["-m", "src.finance_mcp.server"],
      "env": {
        "PYTHONPATH": "/FULL/PATH/finance-mcp",
        "GOOGLE_SHEETS_ID": "your_spreadsheet_id_here",
        "SERVICE_ACCOUNT_JSON": "/FULL/PATH/finance-mcp/credentials/service_account.json"
      }
    }
  }
}

Replace /FULL/PATH/ with the absolute path to the project on your machine, then restart Claude Desktop.

Example prompts:

• "How much did I spend last month?"

• "Show me my top spending categories for April."

• "I paid $80 at the grocery store today — log it."

• "Am I over budget anywhere this month?"

• "Forecast my savings for next month."

• "Generate a financial report for March."

Security note: add_transaction always asks for explicit confirmation before writing to your spreadsheet. The LLM will summarize the transaction and say "Do you confirm?" before calling the tool.

Roadmap

• Multi-currency support

• Recurring transaction detection

• Chart/visualization exports (PNG)

• Support for multiple spreadsheet profiles

• Web dashboard (read-only view)

See the open issues for a full list of proposed features and known issues.

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also open an issue with the tag enhancement. Don't forget to give the project a star!

1. Fork the Project

2. Create your Feature Branch (git checkout -b feature/AmazingFeature)

3. Commit your Changes (git commit -m 'Add some AmazingFeature')

4. Push to the Branch (git push origin feature/AmazingFeature)

5. Open a Pull Request

Top contributors:

Contact

Doğanay Balaban — GitHub

Project Link: https://github.com/DoganayBalaban/finance-mcp

Acknowledgments

• FastMCP — MCP server framework for Python

• gspread — Google Sheets API client

• Model Context Protocol — Open protocol by Anthropic

• Best-README-Template