UNLOCK MLS RESO Reference MCP Server
A Model Context Protocol (MCP) server that provides standardized access to UNLOCK MLS real estate data through Bridge Interactive's RESO Web API. This server enables AI applications like Claude to query, analyze, and interact with real estate listings data.
Features
🏠 Property Search & Analysis
- Natural Language Search: Use conversational queries like "3 bedroom house under $500k in Austin TX"
- Advanced Filtering: Precise search with price ranges, property types, location, and features
- Detailed Property Information: Comprehensive property details including photos, descriptions, and agent information
- Market Analysis: Real-time market trends, pricing statistics, and inventory analysis
🏘️ Market Intelligence
- Price Trend Analysis: Understand market direction and pricing patterns
- Inventory Analysis: Supply and demand indicators for informed decisions
- Comparative Market Analysis: Compare different areas and property types
- Investment Metrics: Data for real estate investment decision-making
👥 Agent & Professional Network
- Agent Search: Find qualified real estate professionals by location, specialization, or office
- Professional Profiles: Access to agent credentials, contact information, and expertise areas
- Local Market Experts: Connect with agents who specialize in specific markets
📊 Comprehensive Resources
- Guided Workflows: Step-by-step guides for common real estate tasks
- Market Insights: Educational resources for understanding market data
- API Status Monitoring: Real-time system health and connectivity information
MCP Server Documentation
- /Users/davidgumpper/Documents/projects/unlock-reso-mcp/docs/README.md
Contributor Resources
- Repository Guidelines: Contributor workflow, tooling expectations, and security practices.
- Claude Integration Guide: Agent-oriented tips for working with this MCP server.
Quick Start
Prerequisites
- Python 3.11 or higher
- uv package manager
- Bridge Interactive API credentials
Installation
-
Clone the repository:
git clone <repository-url> cd unlock-reso-mcp -
Install dependencies:
uv sync --dev -
Configure environment variables:
cp .env.example .env # Edit .env with your Bridge Interactive credentials -
Run the MCP server:
python -m main
Environment Configuration
Create a .env file in the project root with the following variables:
# Bridge Interactive API Configuration (Required)
BRIDGE_SERVER_TOKEN=your_server_token_here
BRIDGE_CLIENT_ID=your_client_id_here
BRIDGE_CLIENT_SECRET=your_client_secret_here
BRIDGE_MLS_ID=your_mls_id_here
BRIDGE_API_BASE_URL=https://api.bridgedataoutput.com/api/v2
# Optional Configuration
LOG_LEVEL=INFO
API_RATE_LIMIT_PER_MINUTE=60
CACHE_ENABLED=false
CACHE_TTL_SECONDS=300
Claude Desktop Integration
Add the following configuration to your Claude Desktop MCP settings:
{
"mcpServers": {
"unlock-mls-mcp": {
"command": "python",
"args": ["-m", "main"],
"cwd": "/path/to/unlock-reso-mcp"
}
}
}
Usage Examples
Property Search
Natural Language Queries:
Find me a 3 bedroom house under $500k in Austin TX
Show me condos with pool downtown Dallas under $400k
Search for single family homes over 2000 sqft in Houston
Structured Search:
{
"filters": {
"city": "Austin",
"state": "TX",
"min_bedrooms": 3,
"max_price": 500000,
"property_type": "single_family"
},
"limit": 25
}
Market Analysis
City-Wide Analysis:
{
"city": "Austin",
"state": "TX",
"property_type": "residential",
"days_back": 90
}
ZIP Code Analysis:
{
"zip_code": "78701",
"property_type": "single_family",
"days_back": 90
}
Agent Search
Find Local Agents:
{
"city": "Austin",
"state": "TX",
"limit": 20
}
Search by Specialization:
{
"specialization": "luxury homes",
"city": "Dallas",
"state": "TX"
}
API Reference
Tools
search_properties
Search for properties using natural language or specific criteria.
Parameters:
query(string, optional): Natural language search queryfilters(object, optional): Structured search filterslimit(integer, optional): Maximum results (default: 25, max: 100)
Example:
{
"query": "3 bedroom house under $500k in Austin TX",
"limit": 25
}
get_property_details
Get comprehensive details for a specific property.
Parameters:
listing_id(string, required): Property listing ID
Example:
{
"listing_id": "LISTING123"
}
analyze_market
Analyze market trends and statistics for a location.
Parameters:
city(string): City namestate(string): State abbreviationzip_code(string): ZIP code (alternative to city/state)property_type(string, optional): Property type filterdays_back(integer, optional): Analysis period in days (default: 90)
Example:
{
"city": "Austin",
"state": "TX",
"property_type": "residential",
"days_back": 90
}
find_agent
Find real estate agents or members.
Parameters:
name(string, optional): Agent name (partial or full)office(string, optional): Office namecity(string, optional): Citystate(string, optional): State abbreviationspecialization(string, optional): Agent specializationlimit(integer, optional): Maximum results (default: 20, max: 50)
Example:
{
"name": "John Smith",
"city": "Austin",
"state": "TX",
"limit": 20
}
Resources
The server provides several informational resources:
- Property Search Examples: Common search query examples and patterns
- Property Types Reference: Guide to property types and status values
- Market Analysis Guide: How to interpret market analysis data
- Agent Search Guide: Finding and working with real estate agents
- Common Workflows: Real estate workflow patterns and best practices
- Guided Property Search: Step-by-step property search workflows
- Guided Market Analysis: Step-by-step market analysis workflows
- API Status & Info: Current system status and configuration
Development
Project Structure
unlock-reso-mcp/
├── src/
│ ├── auth/ # OAuth2 authentication
│ ├── config/ # Configuration and settings
│ ├── utils/ # Data mapping and validation utilities
│ ├── reso_client.py # RESO API client
│ └── server.py # Main MCP server implementation
├── tests/ # Test suite
├── context/ # API documentation and examples
├── main.py # Entry point
└── pyproject.toml # Project configuration
Development Commands
# Install development dependencies
uv sync --dev
# Run tests
pytest
# Run tests with coverage
pytest --cov=src --cov-report=html
# Run linting
ruff check src tests
# Run type checking
mypy src
# Run a specific test
pytest tests/test_oauth2.py -v
# Run tests matching pattern
pytest -k "test_search" -v
Testing
The project includes enterprise-grade test coverage:
- Unit Tests: All modules have dedicated test files (141+ core tests)
- Integration Tests: End-to-end workflow testing with real API validation
- Performance Tests: Benchmarking with 17,000+ operations/second capacity
- Error Scenario Tests: Comprehensive error handling validation (24+ tests)
- Load Tests: Production readiness validation with concurrent user simulation
- Real API Testing: Validated with live Bridge Interactive RESO Web API
- Mock Testing: Comprehensive fixtures for development and CI/CD
- Coverage: 85% code coverage with quality validation
Architecture
The server is built with the following components:
- MCP Server Framework: Uses the standard
mcp.serverframework for MCP compliance - Bearer Token Authentication: Server token authentication using
BRIDGE_SERVER_TOKEN - RESO API Client: Async HTTP client with OData query building capabilities
- Data Mapping: Translates RESO fields to user-friendly formats
- Natural Language Processing: Parses conversational search queries into structured filters
- Comprehensive Error Handling: Graceful degradation with user-friendly error messages
Bridge Interactive API
This server integrates with Bridge Interactive's RESO Web API to provide access to UNLOCK MLS data. The API follows RESO Data Dictionary 2.0 standards for consistent field naming and data structures.
API Endpoints Used
- Authentication: Bearer token using
BRIDGE_SERVER_TOKEN - Property Data:
/OData/{MLS_ID}/Property- Property listings and details - Member Data:
/OData/{MLS_ID}/Member- Real estate agent information - Office Data:
/OData/{MLS_ID}/Office- Brokerage office details - Lookup Data:
/OData/{MLS_ID}/Lookup- Reference data and metadata
Data Standards
All data returned follows RESO Data Dictionary 2.0 specifications:
- Standardized field names and formats
- Consistent property status values
- Uniform address and contact information structure
- Standardized property types and features
Troubleshooting
Common Issues
Authentication Errors
- Verify Bridge Interactive API credentials in
.envfile - Check that
BRIDGE_SERVER_TOKENis correct and valid - Ensure proper
BRIDGE_MLS_IDis configured for your access - Ensure network connectivity to
api.bridgedataoutput.com
No Search Results
- Check city name spelling and state abbreviation
- Try broader search criteria (increase price range, reduce requirements)
- Verify the area has MLS coverage through UNLOCK
Server Connection Issues
- Ensure Python 3.11+ is installed
- Check that all dependencies are installed with
uv sync --dev - Verify the server is running on the correct transport (stdio)
Debug Mode
Enable debug logging by setting the environment variable:
LOG_LEVEL=DEBUG
This will provide detailed information about API calls, authentication, and data processing.
Support
For technical support:
- Check the troubleshooting section above
- Review server logs for error details
- Verify environment configuration
- Test API connectivity with Bridge Interactive
License
This project is licensed under the MIT License - see the LICENSE file for details.
Contributing
Contributions are welcome! Please follow these steps:
- Fork the repository
- Create a feature branch
- Make your changes with tests
- Ensure all tests pass and coverage is maintained
- Submit a pull request
Development Guidelines
- Follow PEP 8 style guidelines
- Add tests for new functionality
- Maintain or improve code coverage
- Update documentation for API changes
- Follow conventional commit message format
Changelog
Version 1.0.0 (Current) - PRODUCTION READY
- ✅ Complete MCP server implementation
- ✅ 4 main tools: search_properties, get_property_details, analyze_market, find_agent
- ✅ 8 comprehensive resources and guides
- ✅ Natural language query processing
- ✅ Real API Integration: Validated with Bridge Interactive RESO Web API
- ✅ Bearer Token Authentication: Server token authentication working
- ✅ RESO Data Dictionary 2.0 compliance
- ✅ Enterprise Testing: 141+ tests with 85% coverage
- ✅ Performance Validated: 17,000+ operations/second capacity
- ✅ Comprehensive documentation
Roadmap
✅ Phase 7: Enhanced Testing Suite (Completed)
- ✅ Integration tests for end-to-end workflows
- ✅ Performance testing and benchmarks
- ✅ Error scenario testing
- ✅ Load testing for production readiness
- ✅ Test data fixtures and utilities
Phase 8: Optimization & Enhancement
- Caching layer for improved performance
- Rate limiting compliance
- Enhanced error handling
Phase 9: Deployment & CI/CD
- Docker containerization
- GitHub Actions workflow
- Deployment documentation
Phase 10: Production Readiness
- Final validation and testing
- Performance optimization
- Production deployment guidelines