README.md•4.69 kB
# Real Estate MCP Server
A Model Context Protocol (MCP) server that provides real estate search and mortgage calculation tools.
## Features
### Available Tools
1. **property.search** - Search for properties with filters
- Location-based search
- Price range filtering
- Bedrooms/bathrooms filtering
- Square footage filtering
- Property type filtering
- Note: Currently returns mock data - real API integration needed
2. **mortgage.calculate** - Calculate monthly mortgage payments
- Principal & interest calculation
- Property tax breakdown
- Insurance costs
- HOA fees
- PMI estimation
3. **mortgage.affordability** - Calculate home affordability
- Estimate maximum home price based on monthly payment budget
- Considers down payment and loan terms
## Installation
### Prerequisites
- Node.js 18+ (check with `node --version`)
- npm or yarn
### Install from Source
```bash
# Clone the repository
git clone https://github.com/klappe-pm/Real-Estate-MCP.git
cd Real-Estate-MCP
# Install dependencies
npm install
# Build the TypeScript code
npm run build
```
### Development Mode
```bash
# Run in watch mode for development
npm run dev
```
## Usage with Claude Desktop
### Configure Claude Desktop
1. Edit your Claude Desktop configuration file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
2. Add the server configuration:
```json
{
"mcpServers": {
"real-estate": {
"command": "node",
"args": ["/path/to/Real-Estate-MCP/dist/index.js"],
"env": {}
}
}
}
```
Replace `/path/to/Real-Estate-MCP` with the actual path to your cloned repository.
3. Restart Claude Desktop
### Using with npx (No Installation)
You can also run directly without cloning:
```json
{
"mcpServers": {
"real-estate": {
"command": "npx",
"args": ["-y", "real-estate-mcp"]
}
}
}
```
Note: This requires publishing to npm first.
## Example Usage in Claude
Once configured, you can use the tools in Claude:
```
"Search for homes in Austin, Texas under $600,000 with at least 3 bedrooms"
"Calculate the monthly mortgage payment for a $500,000 home with 20% down,
6.5% interest rate, 30-year term, $6000/year property tax, and $1200/year insurance"
"What's the maximum home price I can afford with a $3000/month budget,
$100,000 down payment, and 6.5% interest rate?"
```
## API Integration
The property search currently returns mock data. To integrate real APIs:
### Zillow Integration
- Use RapidAPI's Zillow endpoints (unofficial)
- Or implement web scraping (check ToS and robots.txt)
- Store API key in environment variables
### Redfin Integration
- No official public API available
- Consider unofficial endpoints or web scraping
- Respect rate limits and ToS
### MLS Integration
- Requires MLS membership or broker partnership
- Different APIs per region (RETS, Web API, etc.)
- Authentication typically required
### Alternative APIs
- Rentberry API
- Realty Mole API
- RentSpree API
- Estated API
## Development
### Project Structure
```
src/
├── index.ts # Main MCP server
├── tools/
│ ├── property-search.ts # Property search implementation
│ └── mortgage-calculator.ts # Mortgage calculations
└── types/
└── real-estate.ts # TypeScript interfaces
```
### Available Scripts
- `npm run dev` - Start development server with hot reload
- `npm run build` - Build TypeScript to JavaScript
- `npm run lint` - Run ESLint
- `npm run type-check` - Check TypeScript types
### Adding New Tools
1. Create a new tool file in `src/tools/`
2. Define the tool's input/output types in `src/types/`
3. Register the tool in `src/index.ts` using `server.tool()`
4. Rebuild with `npm run build`
## Environment Variables
For production API integration, set these environment variables:
```bash
ZILLOW_API_KEY=your_api_key
REDFIN_API_KEY=your_api_key
MLS_API_KEY=your_api_key
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request
## License
MIT - See LICENSE file for details
## Support
For issues and questions:
- GitHub Issues: https://github.com/klappe-pm/Real-Estate-MCP/issues
## Roadmap
- [ ] Integrate real Zillow API
- [ ] Add Redfin data source
- [ ] MLS integration
- [ ] Add rental property search
- [ ] Investment property analysis tools
- [ ] Comparative market analysis (CMA)
- [ ] Property valuation estimates
- [ ] Neighborhood data integration
- [ ] School district information
- [ ] Crime statistics
- [ ] Walk/transit scores