💰 Personal Finance MCP Server

mcp-name: io.github.sarveshtalele/personal-finance

Deterministic personal finance calculator powered by Model Context Protocol — based on the Core Financial Principles.

✨ What It Does

Connect this server to Claude Desktop, Claude Code, or any MCP client to get 54 financial calculation tools with:

• 🔢 Deterministic outputs — same inputs → same results, always
• 📖 Theory-grounded — every formula traced to core financial concepts
• 📐 Full formula display — shows the exact calculation, not just the answer
• 🇮🇳 Indian finance context — ₹ formatting, SIP planning, EMI calculations
• 🚀 Zero external APIs — works fully offline, no LLM dependency for math

📦 Quick Start

1. Connect to Claude Desktop (Zero-Install Method)

Because this tool is globally published to PyPI, you don't even need to download the code to use it. Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "personal-finance": {
      "command": "uvx",
      "args": [
        "personal-finance-mcp"
      ]
    }
  }
}

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

Restart Claude Desktop, and you will see the integration automatically.

2. Manual Global Installation

If you'd like to use it natively from your terminal without uv, just install it via standard pip:

pip install personal-finance-mcp

# Starts the server!
personal-finance-mcp

🛠 Tool Categories (54 Tools)

📊 Time Value of Money — 10 tools

💳 Debt Management — 6 tools

📋 Financial Planning — 9 tools

📈 Bond Analysis — 6 tools

📊 Stock Valuation — 5 tools

🏦 Mutual Funds — 7 tools

📊 Portfolio Analytics — 11 tools

💬 Example Usage in Claude

"Calculate EMI for a 50 lakh home loan at 8.5% for 20 years"

Output:

══════════════════════════════════════════════════
  EMI Calculation
══════════════════════════════════════════════════
  Emi: ₹43,391.16
  Total Payment: ₹1,04,13,878.40
  Total Interest: ₹54,13,878.40
  Interest To Principal Ratio: 1.0828
  Principal: ₹50,00,000.00
  Annual Rate: 8.5%
  Tenure Months: 240

  Formula: EMI = 50,00,000.00 × 0.007083 × (1+0.007083)^240 / ((1+0.007083)^240 - 1)

  

🏗 Architecture

Tools Layer  ───────→  Models Layer
     │                      │
  MCP interface        Pydantic validation
  + core math               + enums

• Tools: FastMCP wrappers + deterministic mathematical functions.
• Models: Pydantic schemas for strict input validation.

See docs/Architecture.md for full details.

📁 Project Structure

personal-finance-mcp/
├── src/
│   ├── server.py              # MCP server entry point
│   ├── __main__.py            # python -m src entry point
│   ├── tools/                 # Pure math & MCP wrappers
│   │   ├── tvm.py             # Time Value of Money
│   │   ├── debt.py            # EMI, amortization
│   │   ├── planning.py        # Financial ratios, health score
│   │   ├── bonds.py           # Bond pricing, YTM, duration
│   │   ├── stocks.py          # DDM, DCF, P/E valuation
│   │   ├── mutual_funds.py    # SIP, SWP, CAGR, NAV
│   │   └── portfolio.py       # MPT, CAPM, Sharpe, alpha
│   ├── models/                # Pydantic validation schemas
│   │   ├── schemas.py         # Type definitions & constraints
│   │   └── enums.py           # Validation Enums
│   └── utils/                 # Formatters & helpers
├── tests/                     # 100+ unit & integration tests
├── docs/                      # documentation & architecture
├── Dockerfile                 # Container deployment
├── run_production.py          # SSE server launcher
├── pyproject.toml             # Package configuration
└── LICENSE                    # MIT License

🚀 Deployment Options

See docs/deployment.md for full instructions.

📚 Documentation

🔑 Key Design Decisions

1. Stateless — No database, no sessions. Every tool call is self-contained.
2. Deterministic — Pure math, no randomness, no AI inference for numbers.
3. Layered — Tools → Calculators → Models, each with single responsibility.
4. Offline-first — Zero external API calls. Works without internet.
5. Theory-grounded — Every formula is mathematically deterministic.

Setup Guide

Prerequisites

• Python 3.10+ (3.12 recommended)
• uv (recommended) or pip
• Claude Desktop or any MCP-compatible client

Installation

Global Installation

Because this tool is globally published to PyPI, you don't even need to download the code to use it if you are using modern tools.

Option 1: Zero-Install (using uvx)

If you have uv installed, it can dynamically fetch and run the package:

uvx personal-finance-mcp

Option 2: Global Pipeline (using pip)

To natively install the executable into your python ecosystem:

pip install personal-finance-mcp

Connect to Claude Desktop

1. Open Claude Desktop settings → Developer → Edit Config
2. Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "personal-finance": {
      "command": "uvx",
      "args": [
        "personal-finance-mcp"
      ]
    }
  }
}

Note: If you don't use uv, you can replace "uvx" with "python" and "args": ["-m", "personal_finance_mcp"].

1. Restart Claude Desktop
2. You should see the hammer icon with 54 tools available

Connect to Claude Code

Claude Code auto-discovers MCP servers. Add to your project's .claude/settings.json:

{
  "mcpServers": {
    "personal-finance": {
      "command": "uvx",
      "args": [
        "personal-finance-mcp"
      ]
    }
  }
}

Run as Standalone Server (SSE)

For remote MCP clients:

# If installed normally:
python -c "from src.server import mcp; mcp.run(transport='sse')"

Server starts at http://127.0.0.1:8000/sse.

Verify Installation

# Run tests
pytest tests/ -v

# Quick smoke test
python -c "from src.server import mcp; print(f'{len(mcp._tool_manager._tools)} tools loaded')"

Dependencies

Troubleshooting

"ModuleNotFoundError: No module named 'src'"

If you're running locally from source, ensure you installed with the -e (editable) flag: uv pip install -e ".[dev]"

Claude Desktop doesn't show tools

• Check the path in config is absolute and correct
• Restart Claude Desktop completely
• Check ~/Library/Logs/Claude/mcp*.log on macOS for errors

Import errors

# Verify the package is installed correctly
python -c "from src.calculators.tvm import future_value; print(future_value(100000, 12, 10, 12))"

📄 License

MIT — free to use, modify, and distribute.