mcrentcast/README.md

mcrentcast - Rentcast MCP Server

A Model Context Protocol (MCP) server that provides intelligent access to the Rentcast API with advanced caching, rate limiting, and cost management features.

🌟 Features

• 🏠 Complete Rentcast API Integration: Access all Rentcast endpoints for property data, valuations, listings, and market statistics
• 💾 Intelligent Caching: Automatic response caching with hit/miss tracking and configurable TTL
• 🛡️ Rate Limiting: Configurable daily/monthly/per-minute limits with exponential backoff
• 💰 Cost Management: Track API usage, estimate costs, and get confirmations before expensive operations
• 🧪 Mock API for Testing: Full mock implementation for development without consuming credits
• ✨ MCP Integration: Seamless integration with Claude and other MCP-compatible clients
• 🐳 Docker Ready: Complete Docker Compose setup for easy deployment
• 📊 Usage Analytics: Track API usage patterns, cache performance, and costs

📋 Table of Contents

• Quick Start
• Installation
• Configuration
• Usage
• MCP Tools
• Mock API
• Development
• Testing
• API Documentation
• Troubleshooting

🚀 Quick Start

Prerequisites

• Python 3.13+
• uv package manager
• Rentcast API key (or use mock mode for testing)

Installation

# Clone the repository
git clone https://git.supported.systems/MCP/mcrentcast.git
cd mcrentcast

# Run the installation script
./install.sh

# IMPORTANT: Set your API key in the .env file
nano .env  # Set RENTCAST_API_KEY=your_actual_api_key

# For development (from cloned repo)
claude mcp add mcrentcast -- uvx --from . mcrentcast

# For production (install from git)
claude mcp add mcrentcast -- uvx --from git+https://git.supported.systems/MCP/mcrentcast.git mcrentcast

📦 Installation

Method 1: Automated Installation

./install.sh

This script will:

• Install Python dependencies with uv
• Create necessary directories
• Initialize the database
• Set up configuration files

Method 2: Manual Installation

# Install dependencies
uv sync

# Create data directory
mkdir -p data

# Initialize database
uv run python -c "from mcrentcast.database import db_manager; db_manager.create_tables()"

# Copy environment configuration
cp .env.example .env

# Edit .env with your API key
nano .env

Using the Installed Scripts

After installation, you can use the provided command-line scripts:

# Run the MCP server (for Claude integration)
uv run mcrentcast

# Run the mock API server (for testing)
uv run mcrentcast-mock-api

Method 3: Docker

# Start with Docker Compose
make dev  # Development mode
make prod # Production mode

⚙️ Configuration

Environment Variables

Create a .env file with your configuration:

# Rentcast API Configuration
RENTCAST_API_KEY=your_api_key_here
RENTCAST_BASE_URL=https://api.rentcast.io/v1

# Mock API Settings (for testing)
USE_MOCK_API=false  # Set to true for testing without credits
MOCK_API_URL=http://localhost:8001/v1

# Rate Limiting
DAILY_API_LIMIT=100
MONTHLY_API_LIMIT=1000
REQUESTS_PER_MINUTE=3

# Cache Settings
CACHE_TTL_HOURS=24
MAX_CACHE_SIZE_MB=100

# Database
DATABASE_URL=sqlite:///./data/mcrentcast.db

Claude Desktop Configuration

Option 1: Using claude mcp add with uvx (Recommended)

# Navigate to the project directory
cd /path/to/mcrentcast

# Make sure your API key is set in .env file
# Edit .env and set RENTCAST_API_KEY=your_actual_key

# For production (install directly from git)
claude mcp add mcrentcast -- uvx --from git+https://git.supported.systems/MCP/mcrentcast.git mcrentcast

# For development (from cloned repository)
claude mcp add mcrentcast -- uvx --from . mcrentcast

# Alternative: use the mcp.json configuration (development only)
claude mcp add mcrentcast .

# For testing with mock API (no real API key needed)
claude mcp add mcrentcast-test -- uvx --from git+https://git.supported.systems/MCP/mcrentcast.git mcrentcast \
  -e USE_MOCK_API=true \
  -e RENTCAST_API_KEY=test_key_basic

# To use different scopes
claude mcp add --scope user mcrentcast -- uvx --from . mcrentcast  # Available to all projects
claude mcp add --scope local mcrentcast .  # Only for current project (default)

Option 2: Manual Configuration

Add to your Claude MCP configuration file (usually ~/.config/claude/mcp.json or similar):

{
  "servers": {
    "mcrentcast": {
      "command": "uv",
      "args": ["run", "python", "-m", "mcrentcast.server"],
      "cwd": "/path/to/mcrentcast",
      "env": {
        "PYTHONPATH": "/path/to/mcrentcast/src:${PYTHONPATH}",
        "RENTCAST_API_KEY": "your_api_key_here",
        "USE_MOCK_API": "false"
      }
    }
  }
}

Note: The server uses the mcp.json file in the project root for configuration when using claude mcp add.

🔧 Usage

With Claude

Once added to Claude, you can use natural language:

User: Search for properties in Austin, Texas

Claude: I'll search for properties in Austin, Texas.
[Uses search_properties tool]
Found 10 properties in Austin, TX...

Direct Python Usage

from mcrentcast.rentcast_client import RentcastClient

async def example():
    client = RentcastClient(api_key="your_key")
    
    # Search properties
    properties, cached, age = await client.get_property_records(
        city="Austin", 
        state="TX", 
        limit=10
    )
    
    # Get value estimate
    estimate, cached, age = await client.get_value_estimate(
        address="123 Main St, Austin, TX"
    )
    
    await client.close()

🛠️ MCP Tools

The server provides 13 MCP tools:

Property Data Tools

Tool	Description	Parameters
search_properties	Search for property records	city, state, zipCode, limit, offset
get_property	Get specific property details	property_id
get_value_estimate	Get property value estimate	address
get_rent_estimate	Get rental price estimate	address, bedrooms, bathrooms, squareFootage

Listing Tools

Tool	Description	Parameters
search_sale_listings	Find properties for sale	city, state, zipCode, limit
search_rental_listings	Find rental properties	city, state, zipCode, limit
get_market_statistics	Get market analysis data	city, state, zipCode

Management Tools

Tool	Description	Parameters
set_api_key	Configure Rentcast API key	api_key
expire_cache	Expire cache entries	cache_key, all
get_cache_stats	View cache performance	-
get_usage_stats	Track API usage and costs	days
set_api_limits	Configure rate limits	daily_limit, monthly_limit, requests_per_minute
get_api_limits	View current limits	-

🧪 Mock API

The project includes a complete mock of the Rentcast API for testing without consuming API credits:

Starting Mock API

Using the Script Command

# Start mock API server (runs on port 8001)
uv run mcrentcast-mock-api

Using Make Commands

# Start mock API only
make mock-api

# Start full stack with mock API
make test-mock

Test API Keys

The mock API includes predefined test keys with different rate limits:

Key	Daily Limit	Use Case
test_key_free_tier	50	Testing free tier
test_key_basic	100	Standard testing
test_key_pro	1,000	High-volume testing
test_key_enterprise	10,000	Unlimited testing
test_key_rate_limited	1	Rate limit testing

Using Mock Mode

To use the mock API instead of the real Rentcast API, set in .env:

USE_MOCK_API=true
RENTCAST_API_KEY=test_key_basic
MOCK_API_URL=http://localhost:8001/v1

Then run the MCP server normally:

uv run mcrentcast

🔬 Development

Project Structure

mcrentcast/
├── src/mcrentcast/       # Core MCP server code
│   ├── server.py         # FastMCP server implementation
│   ├── rentcast_client.py # Rentcast API client
│   ├── database.py       # Database management
│   ├── models.py         # Data models
│   ├── config.py         # Configuration
│   └── mock_api.py       # Mock API server
├── tests/                # Test suite
├── docs/                 # Documentation
├── scripts/              # Utility scripts
├── docker-compose.yml    # Docker configuration
├── Makefile             # Build automation
└── pyproject.toml       # Python dependencies

Running Locally

# Install development dependencies
uv sync --dev

# Run tests
uv run pytest

# Run with mock API
USE_MOCK_API=true uv run python -m mcrentcast.server

# Run linting
uv run ruff check src/

# Format code
uv run black src/ tests/

Docker Development

# Build images
make build

# Start development environment
make dev

# View logs
make logs

# Run tests in container
make test

# Access shell
make shell

🧪 Testing

Unit Tests

uv run pytest tests/ -v

Integration Tests

# Start mock API
make mock-api

# Run integration tests
uv run pytest tests/test_integration.py -v

Test Coverage

uv run pytest --cov=src --cov-report=html
# View report at htmlcov/index.html

📚 API Documentation

Rentcast API Endpoints

The server integrates with all major Rentcast endpoints:

• Property Records: Search and retrieve property information
• Value Estimates: Get property valuations
• Rent Estimates: Calculate rental prices
• Sale Listings: Find properties for sale
• Rental Listings: Find rental properties
• Market Statistics: Access market trends and analytics

Response Caching

All API responses are automatically cached:

• Default TTL: 24 hours (configurable)
• Cache hit/miss tracking
• Manual cache expiration available
• Cache size management

Rate Limiting

Configurable rate limits:

• Daily request limits
• Monthly request limits
• Per-minute rate limiting
• Exponential backoff on failures

🔍 Troubleshooting

Common Issues

Server won't start

# Check Python version
python --version  # Should be 3.13+

# Reinstall dependencies
uv sync --reinstall

# Check database
rm -f data/mcrentcast.db
uv run python -c "from mcrentcast.database import db_manager; db_manager.create_tables()"

API Key Issues

# Test with mock API
USE_MOCK_API=true uv run python scripts/test_mock_api.py

# Verify API key
curl -H "X-Api-Key: your_key" https://api.rentcast.io/v1/properties

Cache Issues

# Clear cache
rm -f data/mcrentcast.db

# Expire specific cache
uv run python -c "
from mcrentcast.database import db_manager
import asyncio
asyncio.run(db_manager.expire_cache_entry('cache_key_here'))
"

Debug Mode

Enable debug logging:

DEBUG=true
LOG_LEVEL=DEBUG

Getting Help

• Check docs/ directory for detailed guides
• Review docs/mock-api.md for testing documentation
• Check docs/claude-setup.md for MCP integration help

📄 License

MIT License - See LICENSE file for details

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Ensure all tests pass
5. Submit a pull request

🙏 Acknowledgments

• Built with FastMCP for MCP support
• Uses Rentcast API for property data
• Powered by uv for Python management

📞 Support

• Documentation: See /docs directory
• Issues: Create an issue on GitHub
• Mock API Guide: See docs/mock-api.md
• Claude Setup: See docs/claude-setup.md

---

Note: This is an unofficial integration with the Rentcast API. Please ensure you comply with Rentcast's terms of service and API usage guidelines.