💰 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.

🌍 Local Development

If you wish to modify the source code:

git clone https://github.com/sarveshtalele/personal-finance-mcp.git
cd personal-finance-mcp
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest tests/ -v

📄 License

MIT — free to use, modify, and distribute.