rental ops mcp

📋 Table of Contents

• 🚀 Quick Start

• ✨ Features

• 🏗️ Architecture

• 🎯 Use Cases

• 📦 Installation

• ⚙️ Configuration

• 🔧 Tool Reference

• 🗺️ Data Sources

• 💰 Pricing

• 🌐 API (Non-MCP)

• 🤝 Contributing

• 📄 License

🚀 Quick Start

Get a fully functional rental AI agent in 30 seconds.

# 1. Install
pip install -r requirements.txt

# 2. Run
python3 server.py

# 3. Add to Claude Desktop (see configuration below)
# Done. Your AI can now search listings, analyze neighborhoods,
# check affordability, compare options, review leases, and more.

That's it. No API keys. No database setup. No Docker required (though we support it). Just Python and an internet connection.

Prerequisites: Python 3.10+, pip, and an internet connection for location & listing data.

✨ Features

Rental Agent packs 8 purpose-built tools covering the entire rental workflow — from finding a place to signing the lease.

Why these tools? Each one solves a concrete problem renters face. Combined, they form an end-to-end rental assistant that would normally require 5+ different websites and a spreadsheet.

🏗️ Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                        YOUR AI AGENT                                 │
│            (Claude Desktop, Cursor, VS Code, Copilot, etc.)          │
└────────────────────────────┬─────────────────────────────────────────┘
                             │
                             ▼
┌──────────────────────────────────────────────────────────────────────┐
│                     Model Context Protocol (MCP)                     │
│                           StdIO Transport                            │
└────────────────────────────┬─────────────────────────────────────────┘
                             │
                             ▼
┌──────────────────────────────────────────────────────────────────────┐
│                         RENTAL AGENT MCP                             │
│                                                                      │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────┐  ┌───────────┐ │
│  │ Search      │  │ Neighborhood │  │ Afford-     │  │ Compare   │ │
│  │ Listings    │  │ Report       │  │ ability     │  │ Listings  │ │
│  └──────┬──────┘  └──────┬───────┘  └──────┬──────┘  └─────┬─────┘ │
│         │                │                 │               │       │
│  ┌──────┴──────┐  ┌──────┴───────┐  ┌──────┴──────┐  ┌─────┴─────┐ │
│  │ Roommate    │  │ Lease        │  │ Commute     │  │ Market    │ │
│  │ Calculator  │  │ Analyzer     │  │ Analysis    │  │ Trends    │ │
│  └──────┬──────┘  └──────┬───────┘  └──────┬──────┘  └─────┬─────┘ │
│         │                │                 │               │       │
└─────────┼────────────────┼─────────────────┼───────────────┼───────┘
          │                │                 │               │
          ▼                ▼                 ▼               ▼
┌──────────────────────────────────────────────────────────────────────┐
│                      DATA SOURCES                                    │
│                                                                      │
│  ┌────────────────┐  ┌────────────────┐  ┌──────────────────────┐   │
│  │  OpenStreetMap  │  │   Nominatim    │  │    DuckDuckGo        │   │
│  │  (Overpass API)  │  │  (Geocoding)   │  │   (Web Search)       │   │
│  │  Amenities,     │  │  Lat/Lon from  │  │  Rental listings,    │   │
│  │  transit, parks │  │  place names   │  │  market data         │   │
│  └────────────────┘  └────────────────┘  └──────────────────────┘   │
│                                                                      │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │              Built-in Calculations Engine                     │   │
│  │  Affordability math │ Rent splitting │ Commute estimation     │   │
│  │  Comparison scoring │ Lease text analysis │ Market insights   │   │
│  └──────────────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────────────┘

Zero external dependencies for data. All sources are free, open, and require no API keys. The calculation engine is built into the server itself.

🎯 Use Cases

🏠 Apartment Hunting

Search listings, compare options with scores, and check neighborhood walkability — all in one conversation.

"Find me 2-bedroom apartments in Austin TX under $2,000, compare the top 3, and tell me about the neighborhoods."

🗺️ Relocation Planning

Moving to a new city? Get neighborhood reports, commute estimates, and market trends before you visit.

"I'm moving to Seattle for a job in South Lake Union. What neighborhoods are within a 30-minute commute and what's the average 1-bedroom rent?"

💰 Budget Planning

Know exactly what you can afford before you start looking. No surprises.

"I make $72,000 a year with $400 in monthly student loans. What rent can I afford using the 50/30/20 rule?"

👥 Roommate Coordination

Fair rent splitting prevents arguments. Choose equal, by-room-size, by-income, or a hybrid.

"Split $3,200 rent between Alice (150 sqft, $50k income), Bob (120 sqft, $60k), and Carol (130 sqft, $45k) using the combined method."

📜 Lease Review

Catch red flags, hidden fees, and unfavorable terms before you sign.

"Here's my lease agreement. Can you analyze it for late fees, pet policy, subleasing restrictions, and maintenance obligations?"

🚗 Commute Optimization

Compare neighborhoods by commute time and cost. The 45-minute threshold can save you thousands.

"Compare commute times from Downtown Austin vs Mueller vs East Austin to my office at 78701."

📦 Installation

pip (Recommended)

git clone https://github.com/Rumblingb/rental-agent-mcp.git
cd rental-agent-mcp
pip install -r requirements.txt
python3 server.py

uv (Fastest Python package manager)

git clone https://github.com/Rumblingb/rental-agent-mcp.git
cd rental-agent-mcp
uv pip install -r requirements.txt
python3 server.py

Docker

docker run -it --rm \
  -v $(pwd):/app \
  -w /app \
  python:3.11-slim \
  bash -c "pip install -r requirements.txt && python3 server.py"

Manual (From Source)

git clone https://github.com/Rumblingb/rental-agent-mcp.git
cd rental-agent-mcp
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install mcp httpx
python3 server.py

Smithery (Cloud Deployment)

One-click deployment to Smithery's cloud infrastructure. No local setup required.

⚙️ Configuration

Environment Variables

None required. Rental Agent works out of the box with zero configuration.

Claude Desktop

1. Open Claude Desktop Settings → Developer → Edit Config

2. Add to claude_desktop_config.json:

{
  "mcpServers": {
    "rental-agent": {
      "command": "python3",
      "args": ["/path/to/rental-agent-mcp/server.py"]
    }
  }
}

VS Code (Cline / Continue)

For Continue extension in VS Code, add to your ~/.continue/config.json:

{
  "experimental": {
    "mcpServers": {
      "rental-agent": {
        "command": "python3",
        "args": ["/path/to/rental-agent-mcp/server.py"]
      }
    }
  }
}

For Cline extension, configure in Cline settings → MCP Servers:

{
  "mcpServers": {
    "rental-agent": {
      "command": "python3",
      "args": ["/path/to/rental-agent-mcp/server.py"]
    }
  }
}

Cursor

1. Open Cursor Settings → Features → MCP Servers

2. Click Add New MCP Server

3. Set Name: rental-agent

4. Set Type: command

5. Set Command: python3 /path/to/rental-agent-mcp/server.py

6. Click Save

🔧 Tool Reference

🔍 rental_search_listings

Search for current rental listings in any city using web search aggregation.

Parameters:

Example:

{
  "location": "Austin TX",
  "max_price": 2000,
  "bedrooms": 2,
  "max_results": 3
}

🏘️ rental_neighborhood_report

Get a comprehensive neighborhood report powered by OpenStreetMap data.

Parameters:

Returns: Restaurants, cafes, bars, supermarkets, gyms, parks, pharmacies, libraries counts within ~1km, plus transit stops, schools, and hospitals.

Example:

{
  "location": "Williamsburg Brooklyn"
}

Sample output:

{
  "neighborhood": "Williamsburg, Brooklyn, Kings County, New York, 11211, USA",
  "walkability": {
    "restaurants": 34,
    "cafes": 12,
    "bars": 18,
    "supermarkets": 4,
    "gyms": 3,
    "pharmacies": 2
  },
  "transit": { "transit_stops_nearby": 9 },
  "schools_nearby": 5,
  "walkability_note": "Higher amenity counts = more walkable. 5+ restaurants + cafes in 1km = very walkable."
}

💰 rental_affordability

Calculate how much rent you can afford based on your income and expenses.

Parameters:

Budget Rules:

• 30% Rule: Max rent = 30% of monthly gross income (landlord standard)

• 50/30/20 Rule: 50% needs (rent within), 30% wants, 20% savings

Example:

{
  "annual_income": 75000,
  "monthly_debt": 300,
  "rule": "30_percent"
}

⚖️ rental_compare

Compare multiple rental options side-by-side with auto-generated scores (0–100).

Parameters:

Listing format:

{
  "listings_json": "[{\"name\":\"Modern Downtown Studio\",\"price\":1800,\"bedrooms\":1,\"sqft\":650,\"neighborhood\":\"Downtown\"},{\"name\":\"East Side 2BR\",\"price\":2200,\"bedrooms\":2,\"sqft\":950,\"neighborhood\":\"East Austin\"},{\"name\":\"North Campus Studio\",\"price\":1200,\"bedrooms\":1,\"sqft\":500,\"neighborhood\":\"North Campus\"}]"
}

Scoring logic: Lower price = better score, more bedrooms = bonus, higher sqft = bonus, low $/sqft = bonus. Scores range 0–100.

👥 rental_roommate_calculator

Split rent fairly among roommates using one of four methods.

Parameters:

Methods:

Example:

{
  "total_rent": 3200,
  "roommates_json": "[{\"name\":\"Alice\",\"room_size_sqft\":150,\"income\":50000},{\"name\":\"Bob\",\"room_size_sqft\":120,\"income\":60000},{\"name\":\"Carol\",\"room_size_sqft\":130,\"income\":45000}]",
  "method": "combined"
}

📜 rental_lease_analyzer

Analyze lease text for key terms, hidden fees, and red flags.

Parameters:

What it detects:

⚠️ Disclaimer: This tool provides informational analysis only and does not constitute legal advice. Always consult a lawyer for important lease decisions.

🚗 rental_commute_analysis

Estimate commute time and monthly cost between two locations.

Parameters:

What it calculates:

• Straight-line distance (km and miles)

• Estimated drive time (avg 50 km/h city speed)

• Estimated transit time (avg 30 km/h + 10 min walk/wait)

• Monthly driving cost (IRS rate: $0.60/mile)

• Monthly transit cost (~$0.15/km)

Example:

{
  "from_location": "Mueller Austin",
  "to_location": "Downtown Austin",
  "commute_days_per_month": 22
}

📈 rental_market_trends

Get rental market context and price trends for any city.

Parameters:

Returns: Web search results for average rental prices, plus estimated affordability based on median income benchmarks for major US cities (NYC, SF, LA, Chicago, Austin, Seattle, Boston, Denver, Miami, Portland, Nashville, Atlanta, Phoenix, Dallas, Houston).

Example:

{
  "city": "Denver, CO"
}

🗺️ Data Sources

Rental Agent uses three free, open data sources — no API keys needed, ever.

OpenStreetMap (Overpass API)

What we use it for: Neighborhood amenities, transit stops, parks, schools, hospitals. Why it's free: OSM is the Wikipedia of maps — a global community of mappers contributing open geographic data. Reliability: Used by Apple Maps, Amazon, Meta, and thousands of other organizations. Updated continuously. Rate limits: Generous — suitable for hundreds of queries per day. No account needed: Public API, anonymous access.

Nominatim (OSM Geocoder)

What we use it for: Converting place names ("Williamsburg Brooklyn") to precise latitude/longitude coordinates. Why it's free: Operated by the OSM Foundation as a public service. Reliability: Powers geocoding for millions of applications worldwide. Usage policy: 1 request per second recommended (we use async with automatic spacing).

DuckDuckGo Instant Answers API

What we use it for: Searching for current rental listings and market trend data. Why it's free: DuckDuckGo provides a public API for non-commercial use. Reliability: Returns structured results from Wikipedia, Wikidata, and DuckDuckGo's index. No rate limiting: Generous access with no API key required.

Built-in Calculations Engine

All financial calculations (affordability, rent splitting, commute costs, comparison scoring, lease analysis) run locally on the server — no external API calls needed.

💰 Pricing

Get Pro: Subscribe Now

The free tier handles 50 queries/day — enough for casual apartment hunting. The Pro tier removes all limits for power users, real estate professionals, and teams.

🌐 API (Non-MCP)

You can also use Rental Agent as a standalone REST API server. This is useful if you want to integrate rental intelligence into your own application without the MCP protocol.

Quick Start (REST Mode)

from server import rental_search_listings, rental_neighborhood_report
import asyncio

async def main():
    # Search listings
    listings = await rental_search_listings(
        location="Austin TX",
        max_price=2000,
        bedrooms=2
    )
    print(listings)

    # Get neighborhood report
    report = await rental_neighborhood_report(
        location="Downtown Austin"
    )
    print(report)

asyncio.run(main())

Building a REST Wrapper

from fastapi import FastAPI
from server import rental_search_listings, rental_neighborhood_report
import asyncio

app = FastAPI()

@app.get("/search")
async def search(location: str, max_price: int = None, bedrooms: int = None):
    result = await rental_search_listings(
        location=location,
        max_price=max_price,
        bedrooms=bedrooms
    )
    return result

@app.get("/neighborhood")
async def neighborhood(location: str):
    result = await rental_neighborhood_report(location=location)
    return result

All 8 tools are async Python functions that accept the same parameters and return JSON strings — ready to be wrapped in any web framework.

🤝 Contributing

We welcome contributions from the community! Here's how to get started:

Development Setup

git clone https://github.com/Rumblingb/rental-agent-mcp.git
cd rental-agent-mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Ways to Contribute

• 🐛 Report bugs — Open an issue with a clear reproduction

• 💡 Suggest features — New tools, data sources, or integrations

• 📝 Improve docs — Better examples, clearer explanations

• 🔧 Submit PRs — Code improvements, bug fixes, new tools

Guidelines

1. Fork the repo and create a feature branch

2. Write clean, typed Python with docstrings

3. Test your changes locally with python3 server.py

4. Open a PR with a clear description of what you changed and why

5. Keep it simple — this project values clarity over cleverness

Roadmap Ideas

• Zillow / Apartments.com direct API integration

• Crime data overlay via open crime databases

• School rating integration (GreatSchools API)

• Transit time calculation using open GTFS data

• Floor plan visualization analysis

• Rent history tracking and prediction

• Multi-language lease analysis

📄 License

MIT License — see LICENSE for details.

MIT License

Copyright (c) 2025 Rumblingb

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions...