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

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