# 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