Mortgage MCP Server

An MCP (Model Context Protocol) server for mortgage loan processing, built with the official Python MCP SDK (FastMCP). Modeled on how an enterprise mortgage system is architected: an AI assistant only ever sees a small set of high-level business tools, while all database access, third-party API calls, and financial logic stay in an internal service layer.

Exposed MCP Tools

Only these six tools are registered on the server — everything else is an internal Python function that Claude/the LLM never sees directly:

Related MCP server: home-slice-mcp

Project Layout

mortgage_mcp/
├── server.py                 # MCP server entry point — wiring only
├── config.py                 # Loads .env, exposes typed settings
├── db.py                     # MySQL connection pool + query helpers
├── requirements.txt
├── .env.example
├── database/
│   └── schema.sql            # Normalized MySQL schema
├── services/                 # ALL business logic lives here (never MCP tools)
│   ├── customer_service.py
│   ├── property_service.py
│   ├── maps_service.py       # Google Geocoding / Places (New) / Routes
│   ├── document_service.py
│   ├── inspection_service.py
│   ├── loan_service.py
│   └── report_service.py
├── tools/
│   └── mortgage_tools.py     # The ONLY module defining MCP tools (thin)
├── documents/                # documents/property_<id>/{sale_deed,owner_id,tax_receipt}.pdf
├── inspections/               # inspection report text files
└── reports/                   # generated PDF mortgage reports

Setup

1. Install dependencies

   pip install -r requirements.txt

2. Create the database

   mysql -u root -p < database/schema.sql

3. Configure environment

   cp .env.example .env
   # then edit .env with your DB credentials and Google Maps API key

   Your Google Cloud project needs the Geocoding API, Places API (New), and Routes API enabled for the key in GOOGLE_MAPS_API_KEY.

4. Seed sample data (optional)

   Insert a customer and property manually via MySQL, or add a small seed script — services/customer_service.insert_customer() and services/property_service.insert_property() are ready to use for this.

5. Run the server

   python server.py

   Or, for local development with the MCP Inspector:

   mcp dev server.py

6. Connect from Claude Desktop / another MCP client

   Add an entry to your client's MCP config pointing at this server, e.g. for Claude Desktop's claude_desktop_config.json:

   {
     "mcpServers": {
       "mortgage-mcp": {
         "command": "python",
         "args": ["/absolute/path/to/mortgage_mcp/server.py"]
       }
     }
   }

Design Notes

• Tools stay thin. Every function in tools/mortgage_tools.py does input validation, calls one or more service functions, and returns a JSON-serializable dict. No SQL and no requests calls appear in that file.

• Geocoding is cached. properties.latitude/longitude are only populated once, on first lookup_property/analyze_locality call for an address; subsequent calls read straight from MySQL.

• Document verification is a seam, not a dead end. document_service.py currently only checks file existence, but verify_sale_deed(), verify_owner_id(), and verify_tax_receipt() are separate functions specifically so OCR or AI-based content verification can be dropped into each one independently later, without touching verify_documents()'s MCP interface.

• Loan policy is configurable, not hard-coded. Max LTV/DTI ratios, minimum credit score, and the base interest rate all come from .env via config.LoanPolicyConfig, so bank rules can be tuned without code changes.

• Reports are self-contained. generate_final_report recomputes the loan evaluation at report-build time (via report_service.py) so the PDF always reflects current data rather than a stale snapshot.

Extending

• Add new MCP tools only in tools/mortgage_tools.py, keeping them thin.

• Add new business logic as functions inside the relevant services/*.py module (or a new service module) — never inline in the tool layer.

• New database tables/columns go in database/schema.sql plus a matching service module function; keep raw SQL out of tools/ and out of server.py.