Skip to main content
Glama
Sign In
Mortgage MCP Server

Mortgage MCP Server

by jibbs1703
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Mortgage MCP Server

A Model Context Protocol (MCP) server that provides mortgage calculation tools for real estate agents and AI assistants.

Features

  • Monthly Payment Calculation: Calculate fixed monthly payments for mortgages

  • Amortization Schedules: Generate complete payment schedules with principal/interest breakdown

  • Lump Sum Payments: Model the impact of lump sum payments on loan payoff

  • Extra Monthly Payments: Calculate accelerated payoff with extra payments

  • Structured Logging: Full observability with structlog

  • Type Safety: 100% typed with Python 3.13+

  • Clean Architecture: Domain → Services → MCP Server layers

Related MCP server: Real Estate MCP Server

Quick Start

Installation

# Create environment
python3.13 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e ".[dev]"

Running the Server

python -m mortgage_mcp_server.server

Running with Docker

The server can run in a Docker container for easier deployment and isolation.

Build the image:

# Using the build script (recommended)
chmod +x build.sh
./build.sh

# Or using docker directly
docker build -t mortgage-mcp-server:latest .

Run the container:

docker run -i mortgage-mcp-server:latest

The -i (interactive) flag is required — it keeps stdin open for MCP stdio communication with VSCode/Claude.

Using Docker Compose:

docker-compose up --build

For full Docker setup and VSCode integration details, see DOCKER.md.

Example: Calculate Monthly Payment

Using the MCP protocol, call the calculate_monthly_payment tool:

{
  "principal": 350000,
  "annual_interest_rate": 6.5,
  "loan_term_years": 30
}

Returns:

{
  "principal": "350000",
  "annual_interest_rate": "6.5",
  "loan_term_years": 30,
  "monthly_payment": "2208.84"
}

Architecture

src/mortgage_mcp_server/
├── domain/           # Pure mortgage calculation logic
│   └── mortgage.py   # Core math (monthly payment, amortization, etc.)
├── schemas/          # Pydantic models for validation
│   └── loan.py       # Input/output schemas
├── services/         # Application orchestration
│   └── calculator.py # Service layer coordinating domain + I/O
├── server.py         # MCP server exposing tools
└── logging.py        # Centralized structlog configuration

Design Principles

  • Domain Layer: Pure functions with no I/O, fully typed, comprehensive docstrings

  • Services Layer: Orchestrates domain logic, validates at boundaries, uses Pydantic

  • MCP Server: Exposes tools via Model Context Protocol

  • Logging: Structured events via structlog for observability

Available Tools

calculate_monthly_payment

Calculate the fixed monthly payment for a mortgage.

Parameters:

  • principal (number): Loan amount in dollars

  • annual_interest_rate (number): Annual rate as percentage (e.g., 6.5)

  • loan_term_years (integer): Loan term in years

Returns: Monthly payment amount

get_amortization_schedule

Get the complete amortization schedule.

Parameters:

  • principal (number): Loan amount

  • annual_interest_rate (number): Annual rate as percentage

  • loan_term_years (integer): Loan term in years

Returns: Full schedule with payment-by-payment breakdown

calculate_with_lump_sum

Model the impact of a lump sum payment at a specific month.

Parameters:

  • principal (number): Loan amount

  • annual_interest_rate (number): Annual rate

  • loan_term_years (integer): Loan term

  • monthly_payment (number): Regular monthly payment

  • lump_sum_amount (number): Lump sum amount

  • month_to_apply (integer): Which month to apply the lump sum

Returns: Updated amortization schedule

calculate_with_extra_payments

Model accelerated payoff with extra monthly payments.

Parameters:

  • principal (number): Loan amount

  • annual_interest_rate (number): Annual rate

  • loan_term_years (integer): Loan term

  • monthly_payment (number): Base monthly payment

  • extra_monthly_payment (number): Extra amount per month

  • num_months_with_extra (integer): How many months to apply extra

Returns: Updated amortization schedule

Testing

# Run tests
pytest tests/

# Run with coverage
pytest --cov=src/mortgage_mcp_server tests/

# View coverage report
pytest --cov=src/mortgage_mcp_server --cov-report=html tests/

VSCode Integration

To use this MCP server with Claude in VSCode, add to your settings.json:

{
  "claude.mcp.servers": {
    "mortgage-calculator": {
      "command": ".venv/bin/python",
      "args": ["-m", "mortgage_mcp_server.server"],
      "cwd": "/Users/jibbs/Documents/git-projects/mortgage-mcp-server",
      "env": {
        "PYTHONPATH": "src"
      }
    }
  }
}

Or with Docker:

{
  "claude.mcp.servers": {
    "mortgage-calculator": {
      "command": "docker",
      "args": ["run", "-i", "mortgage-mcp-server:latest"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

After updating settings, restart VSCode. Claude will now have access to all 4 mortgage calculation tools.

Quality Assurance

# Lint
ruff check src/ tests/

# Format
ruff format src/ tests/

# Check formatting
ruff format --check src/ tests/

# Type check (when Ty is installed)
ty check

Development

This project follows clean architecture principles and the conventions in .github/copilot-instructions.md.

Key Conventions

  • Python 3.13+ with strict type checking

  • Ruff for linting and formatting

  • Pytest for testing

  • Pydantic for input validation

  • Structlog for structured logging

  • Decimal for precise financial calculations

Making Changes

  1. Implement in appropriate layer (domain/services/server)

  2. Add/update types (no Any unless justified)

  3. Add docstrings to public APIs

  4. Write tests for new functionality

  5. Run quality checks:

    ruff check .
ruff format .
pytest tests/

  6. Verify all checks pass before committing

License

MIT

Available Tools

7 tools
calculate_affordabilityA

Calculate the maximum affordable mortgage using standard DTI guidelines.

Applies the conventional 28% front-end (housing-only) and 43% back-end (all-debt) debt-to-income limits. The binding constraint determines the maximum monthly payment, which is then inverted to a maximum loan principal. Purchase price projections are shown for 3%, 5%, 10%, and 20% down payments.

Args: annual_gross_income: Borrower's gross annual income before taxes. monthly_debt_payments: Existing monthly obligations (car, student loans, etc.). annual_interest_rate: Target mortgage rate as a percentage. loan_term_years: Desired loan term in years.

Returns: JSON object with max loan amount, payment caps, and purchase price scenarios.

Inputs: loan_term_years (required), annual_gross_income (required), annual_interest_rate (required), monthly_debt_payments (requi… Returns: result

calculate_monthly_paymentB

Calculate the fixed monthly payment for a mortgage.

Args: principal: Loan amount in dollars (e.g., 350000). annual_interest_rate: Annual interest rate as a percentage (e.g., 6.5). loan_term_years: Loan term in years (e.g., 30).

Returns: JSON object with the monthly_payment field.

Inputs: principal (required), loan_term_years (required), annual_interest_rate (required). Returns: result

calculate_refinance_break_evenA

Analyse whether refinancing a mortgage makes financial sense.

Computes the monthly savings from switching to the new rate, the break-even month at which those savings recover the closing costs, and the net interest impact over the remaining loan life.

Args: current_balance: Remaining principal on the existing loan in dollars. current_annual_rate: Current loan's annual rate as a percentage. remaining_months: Number of payments remaining on the current loan. new_annual_rate: Proposed new loan's annual rate as a percentage. closing_costs: Total closing costs for the refinance in dollars. new_term_years: Term for the new loan in years.

Returns: JSON object with break-even timeline, interest savings, and a recommendation.

Inputs: closing_costs (required), new_term_years (required), current_balance (required), new_annual_rate (required), +2 more. Returns: result

calculate_with_extra_paymentsA

Calculate accelerated payoff from extra monthly payments for a fixed period.

The extra amount is added to every payment for the first num_months_with_extra months. The loan then reverts to the base payment for any remaining balance, reaching payoff earlier than the original term.

Args: principal: Loan amount in dollars. annual_interest_rate: Annual interest rate as a percentage. loan_term_years: Original loan term in years. monthly_payment: Base monthly payment amount. extra_monthly_payment: Extra amount added each month during the extra period. num_months_with_extra: Number of months to make the extra payment.

Returns: JSON object with the updated amortization schedule.

Inputs: principal (required), loan_term_years (required), monthly_payment (required), annual_interest_rate (required), +2 more. Returns: result

calculate_with_lump_sumA

Calculate the amortization schedule after a one-time lump sum payment.

The lump sum is applied at the specified month, reducing the outstanding balance. The remaining schedule uses the same monthly payment against the lower principal, resulting in a shorter loan term.

Args: principal: Loan amount in dollars. annual_interest_rate: Annual interest rate as a percentage. loan_term_years: Original loan term in years. monthly_payment: Regular monthly payment amount. lump_sum_amount: One-time extra payment to apply. month_to_apply: Month (1-based) when the lump sum is applied.

Returns: JSON object with the updated amortization schedule.

Inputs: principal (required), month_to_apply (required), loan_term_years (required), lump_sum_amount (required), +2 more. Returns: result

compare_loan_scenariosA

Compare two loan scenarios side by side.

Returns full amortization schedules for both scenarios plus structured difference metrics: monthly payment delta, total interest delta, total cost delta, term length delta, and which scenario wins on each dimension.

Typical uses: compare 15-year vs. 30-year loans, compare two different rates on the same principal, or compare different loan amounts.

Args: label_a: Human-readable label for scenario A (e.g., "30-year at 6.5%"). principal_a: Loan amount for scenario A in dollars. annual_interest_rate_a: Annual rate for scenario A as a percentage. loan_term_years_a: Term for scenario A in years. label_b: Human-readable label for scenario B. principal_b: Loan amount for scenario B in dollars. annual_interest_rate_b: Annual rate for scenario B as a percentage. loan_term_years_b: Term for scenario B in years.

Returns: JSON object with both schedules and computed comparison metrics.

Inputs: label_a (required), label_b (required), principal_a (required), principal_b (required), +4 more. Returns: result

get_amortization_scheduleB

Get the complete month-by-month amortization schedule.

Args: principal: Loan amount in dollars. annual_interest_rate: Annual interest rate as a percentage. loan_term_years: Loan term in years.

Returns: JSON object with payment_info and the full entries list.

Inputs: principal (required), loan_term_years (required), annual_interest_rate (required). Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct mortgage calculation: monthly payment, amortization schedule, lump sum, extra payments, scenario comparison, refinance break-even, and affordability. Overlap between calculate_monthly_payment and get_amortization_schedule is minimal because the latter returns a full schedule while the former returns just the payment.

    Naming Consistency5/5

    All tool names use snake_case with a clear verb_noun or verb_noun_phrase pattern (calculate_*, get_*, compare_*). The convention is applied consistently across all seven tools.

    Tool Count5/5

    Seven tools is well within the ideal 3-15 range and each tool provides a distinct calculation needed for mortgage analysis. No tool feels redundant or out of scope.

    Completeness4/5

    The suite covers core fixed-rate mortgage calculations from affordability through amortization, extra payments, and refinancing. Minor gaps exist for specialized products like ARMs or interest-only loans, and no tool includes taxes/insurance/PMI in payment calculations.

    Resources

    Related MCP Connectors

    Related MCP Servers

    • RateSpot MCP Server

      zad0xlik
      A
      license
      D
      quality
      D
      maintenance
      Provides access to RateSpot.io mortgage rate APIs, enabling AI assistants to fetch real-time mortgage rates, compare loan products, calculate payments, and access comprehensive lending information.
      7
      MIT

    • Real Estate MCP Server

      klappe-pm
      A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables real estate property searches with location and criteria filtering, plus comprehensive mortgage calculations including monthly payments and affordability analysis. Currently uses mock data for property searches but provides full mortgage calculation functionality.
      -

    • Cal MCP Server

      askcal
      A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to answer mortgage-related queries by providing tools for lender search, loan limit lookup, down-payment assistance programs, and more, with data sourced from real wholesale lenders and broker-curated intel.
      8
      5 npm
      MIT