agentic-ops/real-estate-mcp
If you are the rightful owner of real-estate-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
A comprehensive Model Context Protocol (MCP) server for real estate data management.
Real Estate MCP Server
A comprehensive Model Context Protocol (MCP) server for real estate data management. This server provides tools, resources, and prompts for property listings, agent management, market analysis, client relationships, and area intelligence.
๐๏ธ Architecture
The server is built with a modular, componentized architecture for maintainability and scalability:
real-estate-mcp/
โโโ main.py # Main server entry point
โโโ utils.py # Core data management utilities
โโโ tools/ # MCP Tools (organized by category)
โ โโโ property_tools.py # Property search, filtering, insights
โ โโโ agent_tools.py # Agent profiles, performance, dashboards
โ โโโ market_tools.py # Market analysis and trends
โ โโโ client_tools.py # Client management and matching
โ โโโ area_tools.py # Area intelligence and amenities
โ โโโ system_tools.py # Data management and system tools
โโโ resources/ # MCP Resources (organized by domain)
โ โโโ property_resources.py # Property-related resources
โ โโโ agent_resources.py # Agent-related resources
โ โโโ market_resources.py # Market analysis resources
โ โโโ client_resources.py # Client management resources
โ โโโ location_resources.py # Area and amenity resources
โโโ prompts/ # MCP Prompts (user-controlled templates)
โ โโโ __init__.py # Central prompt registration
โ โโโ property_prompts.py # Property analysis and comparison prompts
โ โโโ client_prompts.py # Client matching and consultation prompts
โ โโโ market_prompts.py # Market analysis and investment prompts
โ โโโ agent_prompts.py # Agent performance and development prompts
โโโ data/ # Real estate data files
โโโ properties/
โโโ agents/
โโโ clients/
โโโ market/
โโโ transactions/
โโโ areas/
โโโ amenities/
๐ Features
MCP Capabilities
- 30+ Tools: Comprehensive real estate operations
- 10 Resources: 5 static resources + 5 dynamic resource templates
- 11 Prompts: User-controlled analysis templates across 4 categories
- SSE Transport: Web-compatible Server-Sent Events endpoint
Tool Categories
๐ Property Management (7 tools)
- Search and filter properties by multiple criteria
- Get property details and comprehensive insights
- Area-based and agent-based property listings
- Market context and comparable analysis
๐ฅ Agent Operations (6 tools)
- Agent profiles and specializations
- Performance dashboards and metrics
- Client and property portfolio management
- Sales tracking and analytics
๐ Market Analysis (7 tools)
- Market overview and price analytics
- Area-specific market performance
- Investment opportunity analysis
- Comparative area analysis
- Transaction tracking
๐ค Client Management (3 tools)
- Client profiles and preferences
- Property matching algorithms
- Budget and criteria-based recommendations
๐๏ธ Area Intelligence (9 tools)
- Comprehensive area reports
- Amenities and demographics
- Schools, parks, shopping, healthcare data
- City overview and area comparisons
โ๏ธ System Management (2 tools)
- Data refresh and cache management
- System statistics and summaries
Resources
Static Resources
realestate://all-properties
: Complete property listingsrealestate://all-agents
: Agent directoryrealestate://market-overview
: Current market trendsrealestate://all-areas
: Area informationrealestate://amenities
: Complete amenities database
Dynamic Resource Templates
realestate://properties/area/{area}
: Area-specific propertiesrealestate://agent/{agent_id}/dashboard
: Agent performance dashboardrealestate://market/area/{area}
: Area market analysisrealestate://property/{property_id}/insights
: Property insightsrealestate://client/{client_id}/matches
: Client property matches
Prompts (11 total)
Property Prompts (2 prompts)
- Property Analysis: Comprehensive property evaluation and insights
- Property Comparison: Side-by-side property comparison analysis
Client Prompts (3 prompts)
- Client Matching: Personalized property recommendations
- Client Consultation: Structured consultation framework
- Client Feedback Analysis: Search strategy refinement
Market Prompts (3 prompts)
- Market Reports: Comprehensive area market analysis
- Investment Analysis: ROI and opportunity assessment
- Comparative Market Analysis: Multi-area comparison
Agent Prompts (3 prompts)
- Agent Performance: Performance dashboards and analysis
- Agent Marketing Strategy: Business development and marketing
- Agent Training Development: Skill enhancement and training plans
๐ฆ Installation
-
Clone the repository:
git clone https://github.com/agentic-ops/real-estate-mcp.git cd real-estate-mcp
-
Install dependencies:
pip install -r requirements.txt
-
Run the server:
python main.py
๐ MCP Inspector
To inspect and debug your MCP server, you can use the MCP Inspector tool:
npx @modelcontextprotocol/inspector
This will launch the MCP Inspector interface, allowing you to:
- Monitor MCP messages in real-time
- Debug tool and resource calls
- Inspect server responses
- Test server functionality
๐ Server Transport
The server uses Server-Sent Events (SSE) transport, making it compatible with:
- Web browsers and HTTP clients
- Traditional MCP clients
- Custom integrations
Connection Details
- SSE Endpoint:
http://127.0.0.1:8000/sse
(for establishing SSE connection) - Message Endpoint:
http://127.0.0.1:8000/messages/
(for posting MCP messages) - Transport: SSE (Server-Sent Events)
- Protocol: MCP (Model Context Protocol)
Web Client Example
// Establish SSE connection
const eventSource = new EventSource('http://127.0.0.1:8000/sse');
eventSource.onmessage = function(event) {
const mcpMessage = JSON.parse(event.data);
// Handle MCP protocol messages
};
// Send MCP messages
async function sendMCPMessage(message) {
const response = await fetch('http://127.0.0.1:8000/messages/', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(message)
});
return response.json();
}
๐ง Component Details
Core Components
utils.py
- Data Management
RealEstateDataManager
: Central data access classPropertyFilter
: Search and filtering utilities- JSON data loading and caching
- Cross-referencing and relationship mapping
main.py
- Server Entry Point
- FastMCP server initialization
- Component registration orchestration
- SSE transport configuration
- Startup logging and diagnostics
Tool Modules
Each tool module follows a consistent pattern:
def register_[category]_tools(mcp: FastMCP):
"""Register all [category] tools with the MCP server"""
@mcp.tool()
def tool_function(parameters) -> str:
"""Tool description"""
# Implementation
return json.dumps(result, indent=2)
Resource Modules
Resources are organized by domain for better maintainability:
Property Resources (property_resources.py
)
- Property listings and search results
- Property insights and market context
- Area-based property filtering
Agent Resources (agent_resources.py
)
- Agent profiles and directories
- Performance dashboards and metrics
Market Resources (market_resources.py
)
- Market overview and trends
- Area-specific market analysis
Client Resources (client_resources.py
)
- Client preference matching
- Property recommendations
Location Resources (location_resources.py
)
- Area information and demographics
- Amenities and local services
Each module follows a consistent pattern:
def register_[domain]_resources(mcp: FastMCP):
"""Register all [domain] resources with the MCP server"""
@mcp.resource("realestate://resource-name")
def resource_function() -> str:
"""Resource description"""
return json.dumps(data, indent=2)
Prompt Templates
Prompts guide AI analysis:
@mcp.prompt()
def analysis_prompt(param: str = "default") -> str:
"""Analysis prompt description"""
return f"""
Detailed analysis instructions for {param}...
"""
๐ Data Structure
The server operates on comprehensive real estate data:
- 5 Properties: Victorian homes, contemporary, luxury, townhouses
- 3 Agents: Specialized real estate professionals
- 6 Clients: Buyers, sellers, investors with preferences
- Multiple Sales: Recent transaction history
- 5 Areas: Downtown Riverside, Woodcrest, Canyon Crest, Arlington Heights, La Sierra
- Amenities: Schools, parks, shopping, healthcare facilities
๐ Usage Examples
MCP Client Examples
For proper MCP client integration, use the MCP protocol with the correct endpoints:
# Establish SSE connection (listen for server messages)
curl -N http://127.0.0.1:8000/sse
# Send MCP messages (in a separate terminal)
# Search properties
curl -X POST http://127.0.0.1:8000/messages/ \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "search_properties", "arguments": {"query": "Victorian"}}}'
# Filter by criteria
curl -X POST http://127.0.0.1:8000/messages/ \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "filter_properties", "arguments": {"min_price": 500000, "max_price": 1000000}}}'
# Get market overview
curl -X POST http://127.0.0.1:8000/messages/ \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 3, "method": "resources/read", "params": {"uri": "realestate://market-overview"}}'
# Match client preferences
curl -X POST http://127.0.0.1:8000/messages/ \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "match_client_preferences", "arguments": {"client_id": "CLI001"}}}'
๐งช Testing
The project includes a comprehensive test suite covering all components and functionality.
Test Structure
tests/
โโโ conftest.py # Pytest configuration and shared fixtures
โโโ unit/ # Unit tests for core components
โ โโโ test_utils.py # RealEstateDataManager and PropertyFilter tests
โ โโโ test_*.py # Additional unit tests
โโโ integration/ # Integration tests for MCP components
โ โโโ test_property_tools.py # Property tools integration tests
โ โโโ test_all_tools.py # All other tool categories
โ โโโ test_resources.py # Static and template resources tests
โ โโโ test_prompts.py # Prompt template tests
โโโ __init__.py
Test Categories
Unit Tests (tests/unit/
)
- Data Manager Tests: Core functionality of
RealEstateDataManager
- Filter Tests: Property filtering logic and edge cases
- Utility Functions: Helper functions and data validation
Integration Tests (tests/integration/
)
- Property Tools: Search, filter, insights, and area-based queries
- Agent Tools: Profile management, performance dashboards
- Market Tools: Market analysis and trend calculations
- Client Tools: Client matching and preference algorithms
- Area Tools: Area intelligence and amenities data
- System Tools: Data refresh and system statistics
- Resources: Static resources and dynamic templates
- Prompts: Template generation and parameter handling (11 prompts across 4 categories)
Running Tests
Prerequisites
# Install testing dependencies
pip install -r requirements.txt
Quick Test Commands
# Run all tests
pytest
# Run with coverage report
pytest --cov=. --cov-report=html
# Run specific test categories
pytest tests/unit/ # Unit tests only
pytest tests/integration/ # Integration tests only
pytest tests/integration/test_property_tools.py # Property tools only
Using the Test Runner Script
# Run all tests
python run_tests.py
# Run specific test types
python run_tests.py unit # Unit tests only
python run_tests.py integration # Integration tests only
python run_tests.py property # Property tools only
python run_tests.py resources # Resource tests only
# Run with verbose output and coverage
python run_tests.py all -v -c
Test Features
Fixtures and Test Data
- Isolated Test Environment: Each test uses temporary data directories
- Mock Data: Consistent test data across all test cases
- Shared Fixtures: Reusable test components in
conftest.py
- Data Manager Mocking: Isolated testing without file system dependencies
Coverage and Reporting
- Code Coverage: Comprehensive coverage reporting with pytest-cov
- HTML Reports: Visual coverage reports in
htmlcov/index.html
- Missing Lines: Identification of uncovered code paths
- Branch Coverage: Logic branch testing
Test Configuration
- pytest.ini: Centralized test configuration
- Automatic Discovery: Tests auto-discovered by naming convention
- Parallel Execution: Support for parallel test execution
- Filtering: Warning filters for clean test output
Test Data Validation
The test suite validates:
- โ All 30+ tools function correctly with mock and real data
- โ Property filtering logic handles edge cases
- โ Search functionality is case-insensitive and comprehensive
- โ Agent performance calculations are accurate
- โ Market analysis tools process data correctly
- โ Client matching algorithms work as expected
- โ Area intelligence aggregates data properly
- โ Resource endpoints return valid JSON
- โ Prompt templates generate proper instructions
- โ Error handling for missing or invalid data
- โ Data refresh and caching mechanisms
- โ System statistics and summaries
Continuous Integration
For CI/CD pipelines, use:
# Basic test run
pytest tests/ --tb=short
# With coverage for CI reporting
pytest tests/ --cov=. --cov-report=xml --cov-report=term-missing
# Specific test categories for staged testing
pytest tests/unit/ --tb=short # Fast unit tests first
pytest tests/integration/ --tb=short # Integration tests second
Writing New Tests
When adding new functionality:
- Unit Tests: Add to
tests/unit/
for core logic - Integration Tests: Add to appropriate
tests/integration/test_*.py
- Use Fixtures: Leverage existing fixtures in
conftest.py
- Mock External Dependencies: Use
unittest.mock
for isolation - Test Edge Cases: Include boundary conditions and error scenarios
- Follow Naming Convention:
test_*.py
files,Test*
classes,test_*
methods
๐ ๏ธ Development
Adding New Tools
- Choose appropriate category in
tools/
- Add tool function with
@mcp.tool()
decorator - Register in the category's
register_*_tools()
function - Import and call registration in
main.py
- Add Tests: Create corresponding tests in
tests/integration/
Adding New Resources
- Choose appropriate domain module in
resources/
(property, agent, market, client, location) - Add resource function with
@mcp.resource()
decorator and URI pattern - Register in the domain's
register_*_resources()
function - Import and call registration in
main.py
- Add Tests: Include resource tests in
tests/integration/test_resources.py
Adding New Prompts
- Choose appropriate category in
prompts/
(property, client, market, or agent) - Add prompt function with
@mcp.prompt()
decorator - Include parameter defaults and comprehensive instructions
- Register in the category's
register_*_prompts()
function - Add Tests: Include prompt tests in
tests/integration/test_prompts.py
Adding New Prompt Categories
- Create new file in
prompts/
directory (e.g.,prompts/new_category_prompts.py
) - Follow the existing pattern with
register_new_category_prompts(mcp)
function - Import and register in
prompts/__init__.py
- Add Tests: Create corresponding test fixtures and test methods
๐ Benefits of SSE Transport
- Web Compatible: Direct browser integration
- Real-time: Server-sent events for live updates
- HTTP Standard: Works with standard HTTP tools
- Firewall Friendly: Uses standard HTTP port
- Scalable: Supports multiple concurrent connections
๐ License
This project is licensed under the MIT License.
๐ค Contributing
- Fork the repository
- Create a feature branch
- Add your component following the established patterns
- Test thoroughly
- Submit a pull request
๐ Further Reading
For a comprehensive deep dive into the architecture, design principles, and real-world applications of this MCP server, read the detailed blog post:
๐ MCP Servers - Model Context Protocol Implementation
The blog post covers:
- Understanding MCP Servers and their business impact
- Architecture deep dive with code examples
- MCP Tools, Prompts, and Resources explained
- Real-world usage scenarios and implementation patterns
- Security considerations and best practices
- Future implications of MCP technology
Built with the Model Context Protocol (MCP) for seamless AI integration