Finance MCP

Personal finance management via Model Context Protocol (MCP).

Overview

This MCP server provides tools for managing personal finances:

• Accounts: Bank accounts, credit cards, savings

• Transactions: Income, expenses, transfers

• Debts: Track debts and payments

• Monthly Payments: Installments (MSI) tracking

• Fixed Expenses: Recurring monthly expenses

• Active Loans: Money others owe to you

• Savings: Goals and movement tracking

• Budgets: Monthly budget limits

• Assets: Personal asset inventory

Related MCP server: Finance MCP Server

Installation

# Clone the repository
git clone https://github.com/FrancoMeneses/finance-mcp.git
cd finance-mcp

# Install dependencies
pip install -r requirements.txt

# Initialize the database (optional - server creates it on first run)
sqlite3 finance.db < schema/init.sql

Usage

With Hermes Agent

Add to ~/.hermes/config.yaml:

mcp_servers:
  finance:
    command: "python3"
    args: ["/path/to/finance-mcp/src/finance/server.py"]
    env:
      DB_PATH: "/path/to/finance.db"

Standalone

# Set database path
export DB_PATH="/path/to/finance.db"

# Run the server
python src/finance/server.py

Available Tools

Accounts

• list_accounts - List all accounts

• get_account - Get account details

• create_new_account - Create a new account

• update_account_balance - Update account balance

Categories

• list_categories - List all categories

• get_category - Get category details

Transactions

• list_transactions - List transactions with filters

• add_transaction - Record a new transaction

Debts

• list_debts - List debts

• get_debt - Get debt details

• add_debt - Register a new debt

• record_debt_payment - Record a debt payment

Monthly Payments (MSI)

• list_monthly_payments - List installments

• add_monthly_payment - Register new installment

Fixed Expenses

• list_fixed_expenses - List fixed expenses

• add_fixed_expense - Add fixed expense

Active Loans

• list_active_loans - List loans given to others

• add_active_loan - Register a new loan

• record_loan_payment - Record payment received

Savings

• list_savings - List savings goals

• get_savings_goal - Get savings goal details

• add_savings_goal - Create savings goal

• record_savings_movement - Deposit/withdraw from savings

• list_savings_movements - View savings history

Budgets

• list_budgets - List budgets

Assets

• list_assets - List personal assets

• get_assets_total - Get total asset value

Summaries

• get_account_overview - Quick account summary

• get_monthly_report - Monthly income/expense report

Database Schema

See schema/init.sql for the complete database schema.

Project Structure

finance-mcp/
├── README.md
├── requirements.txt
├── schema/
│   └── init.sql         # Database schema
├── src/
│   └── finance/
│       ├── __init__.py
│       ├── server.py    # MCP server (FastMCP)
│       ├── db.py        # Database access layer
│       └── models.py    # Pydantic validation models
├── tests/
│   └── ...
└── docs/
    └── architecture.md

License

MIT