Skip to main content
Glama
finance-engines

finance-engines

by vmagapu

finance-engines-mcp

Deterministic financial math as MCP tools — because LLMs should exercise judgment, not arithmetic.

tests

The pattern

Language models are excellent at deciding when a calculation is needed and what the result means for a user. They are unreliable at the calculation itself — and in financial software, a plausible-but-wrong number is worse than no number.

This server implements the separation I use in production at MoneyCompass, an AI financial advisor where every number the model presents comes from a deterministic engine layer, never from token prediction:

┌─────────────┐     tool call      ┌──────────────────────┐
│   LLM        │ ─────────────────▶ │  finance-engines-mcp  │
│  (judgment:  │                    │  (arithmetic:         │
│   when, why, │ ◀───────────────── │   Decimal, tested,    │
│   so what)   │   exact result +   │   reproducible)       │
└─────────────┘    assumptions      └──────────────────────┘

Design rules this repo demonstrates:

  • Pure functions. No state, no side effects, no network. Same inputs → same outputs, forever.

  • Decimal arithmetic. Money is never represented in binary floating point internally; rounding is explicit (ROUND_HALF_UP, cents for money, basis points for rates).

  • Assumptions travel with results. Every projection returns the assumptions it used, so the model can (and should) disclose them.

  • Schedules reconcile. The loan engine walks the amortization month by month so totals match to the cent — not just the closed-form payment formula.

  • Errors are errors. Unreachable goals and invalid inputs raise, rather than returning something plausible.

Related MCP server: Finance MCP Server

Tools

Tool

What it answers

compound_growth

"What will my investment be worth?" — monthly compounding + contributions

loan_amortization

"What does this loan really cost?" — payment, total interest, first/last payment split

effective_annual_rate

"Which rate is actually better?" — nominal APR → EAR

inflation_adjusted

"What is that worth in today's dollars?"

savings_goal_months

"When do I hit my target?" — exact monthly simulation

retirement_projection

"Will I be ready?" — nominal and real, assumptions disclosed

Install & use

pip install git+https://github.com/vmagapu/finance-engines-mcp

Claude Code:

claude mcp add finance-engines -- python -m finance_engines_mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "finance-engines": {
      "command": "python",
      "args": ["-m", "finance_engines_mcp"]
    }
  }
}

Then ask: "If I invest $100k at 7% and add $1,000/month, what's that worth in 20 years — in today's dollars?" — and watch the model route the arithmetic here instead of guessing.

Development

pip install -e ".[dev]"
pytest

Tests pin the engines to independently verifiable reference values (the classic $300k/6%/30yr mortgage at $1,798.65/month, textbook EAR conversions, annuity formulas) plus reconciliation and error-path cases.

Why so small?

Deliberately. The point is the boundary, not the library: in an agentic system, the interesting engineering is deciding what the model must not be allowed to improvise. Everything behind that boundary should be boring, typed, tested code. This repo is the boundary, demonstrated.

— Vish Magapu · MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI assistants with access to 30+ validated financial independence calculation functions, eliminating hallucinations by ensuring accurate calculations for retirement planning, CoastFI, investment returns, and other FI metrics.
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables financial calculations such as compound interest, loan EMI, and savings goal projections through natural language.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides retirement planning computations for AI agents, including Monte Carlo simulations, tax burden modeling across all US states, Social Security claiming optimization, and cost-of-living comparisons.
      7 npm
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Provides 77 deterministic financial calculators, live market data, and a meta-advisor that chains tools into prioritized plans from plain-language descriptions.
      77
      7
      MIT