🏠 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)

Installation

# 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

# 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:

{
  "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:

{
  "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

# 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

# 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:

🔍 [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
• Model Context Protocol
• MCP 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