README.md•8.45 kB
# 🏠 Rentcast MCP Server
A Model Context Protocol (MCP) server that provides access to Rentcast Real Estate API data through a standardized interface. This server enables AI assistants and applications to retrieve comprehensive real estate information including property details, market analysis, rent estimates, and property valuations.
## ✨ Features
- **🔍 Property Search**: Search properties with filters (city, state, bedrooms, bathrooms, etc.)
- **🎲 Random Properties**: Get random properties for market analysis
- **📊 Market Analysis**: Comprehensive market statistics and trends
- **💰 Property Valuation**: Automated property value estimates with comparables
- **🏠 Rent Estimates**: Long-term rent estimates with comparable properties
- **🏘️ Sale Listings**: Current properties for sale
- **🏘️ Rental Listings**: Current properties for rent
- **🏠 Property Details**: Detailed property information and parameters
## 🚀 Quick Start
### Prerequisites
- Node.js 18+
- Rentcast API key ([Get one here](https://rentcast.io/))
### Installation
```bash
# Clone the repository
git clone https://github.com/tandat8503/mcp_rentcast.git
cd mcp_rentcast
# Install dependencies
npm install
# Copy environment file
cp .env.example .env
# Edit .env with your Rentcast API key
RENTCAST_API_KEY=your_api_key_here
# Build the project
npm run build
# Start the server
npm start
```
### Using with MCP Inspector
```bash
# Start MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js
# Open browser at http://localhost:6274
# Use the provided auth token to access the interface
```
## 🛠️ Available Tools
### 1. **search_properties**
Search for properties with comprehensive information.
**Parameters:**
- `city` (optional): City name (e.g., "Austin", "New York")
- `state` (optional): State abbreviation (e.g., "TX", "CA")
- `zipCode` (optional): ZIP code (e.g., "78705")
- `bedrooms` (optional): Number of bedrooms (1-10)
- `bathrooms` (optional): Number of bathrooms (1-10)
- `propertyType` (optional): Property type (e.g., "Single Family", "Condo")
- `limit` (optional): Maximum results (default: 15, max: 50)
**Example:**
```json
{
"city": "Austin",
"state": "TX",
"bedrooms": 2,
"limit": 20
}
```
### 2. **get_random_properties**
Get random properties for market analysis.
**Parameters:**
- `city` (optional): City name
- `state` (optional): State abbreviation
- `zipCode` (optional): ZIP code
- `limit` (optional): Number of properties (default: 10, max: 50)
### 3. **analyze_market**
Get comprehensive market statistics and trends.
**Parameters:**
- `zipCode` (optional): ZIP code for analysis
- `city` (optional): City name
- `state` (optional): State abbreviation
- `dataType` (optional): "All", "Sale", or "Rental" (default: "All")
### 4. **get_property_value**
Get automated property value estimates.
**Required (one of):**
- `address`: Full property address
- `latitude` + `longitude`: GPS coordinates
- `propertyId`: Unique property identifier
**Optional:**
- `propertyType`: Property type
- `bedrooms`: Number of bedrooms
- `bathrooms`: Number of bathrooms
- `squareFootage`: Property size in sq ft
**Example:**
```json
{
"address": "1011 W 23rd St, Austin, TX 78705",
"propertyType": "Apartment",
"bedrooms": 1,
"bathrooms": 1
}
```
### 5. **get_rent_estimates**
Get long-term rent estimates with comparable properties.
**Required (one of):**
- `address`: Full property address
- `latitude` + `longitude`: GPS coordinates
- `propertyId`: Unique property identifier
**Optional:**
- `propertyType`: Property type
- `bedrooms`: Number of bedrooms
- `bathrooms`: Number of bathrooms
- `squareFootage`: Property size in sq ft
### 6. **get_sale_listings**
Get current properties for sale.
**Parameters:**
- `city` (optional): City name
- `state` (optional): State abbreviation
- `zipCode` (optional): ZIP code
- `limit` (optional): Maximum results (default: 15, max: 50)
### 7. **get_rental_listings**
Get current properties for rent.
**Parameters:**
- `city` (optional): City name
- `state` (optional): State abbreviation
- `zipCode` (optional): ZIP code
- `limit` (optional): Maximum results (default: 15, max: 50)
### 8. **get_property_details**
Get detailed property information.
**Parameters:**
- `id` (required): Property or listing ID
### 9. **get_server_status**
Get server status and API usage information.
**Parameters:** None
## 🔧 Configuration
### Environment Variables
| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `RENTCAST_API_KEY` | Your Rentcast API key | - | ✅ |
| `RENTCAST_BASE_URL` | Rentcast API base URL | `https://api.rentcast.io/v1` | ❌ |
| `MAX_API_CALLS_PER_SESSION` | Maximum API calls per session | `40` | ❌ |
| `TIMEOUT_SECONDS` | API call timeout | `30` | ❌ |
| `ENABLE_RATE_LIMITING` | Enable rate limiting | `true` | ❌ |
| `RATE_LIMIT_PER_MINUTE` | Rate limit per minute | `60` | ❌ |
| `DEBUG` | Enable debug mode | `false` | ❌ |
| `LOG_LEVEL` | Log level | `INFO` | ❌ |
### API Limits
- **Free Tier**: 45 API calls per month
- **Default Session Limit**: 40 calls per session
- **Rate Limiting**: 60 calls per minute (configurable)
## 🏗️ Project Structure
```
mcp_rentcast/
├── src/
│ ├── index.ts # Main MCP server implementation
│ ├── services/
│ │ ├── config.ts # Configuration service
│ │ └── rentcast-api.ts # Rentcast API client
│ └── types/
│ └── index.ts # TypeScript type definitions
├── dist/ # Compiled JavaScript output
├── package.json # Project dependencies and scripts
├── tsconfig.json # TypeScript configuration
├── .env.example # Environment variables template
├── .gitignore # Git ignore patterns
└── README.md # This file
```
## 🚀 Development
### Scripts
```bash
# Build the project
npm run build
# Start in development mode with hot reload
npm run dev
# Start production server
npm start
# Run tests
npm test
# Lint code
npm run lint
# Format code
npm run format
```
### Building
```bash
# Development build
npm run build
# The compiled output will be in the `dist/` directory
```
### Debug Mode
The server includes comprehensive console logging for debugging:
- **Input Parameters**: Logs all parameters received by tools
- **API Responses**: Logs API call results and data samples
- **Error Handling**: Detailed error logging with context
- **Performance**: API call counts and rate limiting information
## 🔍 Debugging
### Console Logs
Each tool provides detailed logging:
```bash
🔍 [tool_name] Tool called with params: { ... }
🔍 [tool_name] Built search params: { ... }
🔍 [tool_name] API result: { ... }
🔍 [tool_name] Data sample: { ... }
🔍 [tool_name] Tool completed successfully
```
### Common Issues
1. **Missing API Key**: Ensure `RENTCAST_API_KEY` is set in `.env`
2. **API Limits**: Monitor remaining API calls with `get_server_status`
3. **Rate Limiting**: Wait between API calls if rate limited
4. **Invalid Parameters**: Check parameter validation in console logs
## 📊 API Usage Optimization
### Best Practices
1. **Batch Requests**: Use higher limits when possible to reduce API calls
2. **Caching**: Implement caching for frequently requested data
3. **Parameter Validation**: Provide accurate parameters for better results
4. **Error Handling**: Implement proper error handling for failed requests
### Rate Limiting
- Default: 60 calls per minute
- Configurable via `RATE_LIMIT_PER_MINUTE`
- Automatic delays between calls when enabled
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## 📝 License
This project is licensed under the MIT License - see the LICENSE file for details.
## 🔗 Links
- [Rentcast API Documentation](https://docs.rentcast.io/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
## 🆘 Support
For issues and questions:
1. Check the console logs for debugging information
2. Verify your API key and configuration
3. Check Rentcast API status and limits
4. Open an issue in the repository
---
**Built with ❤️ for the MCP community**