agentic-ops/real-estate-mcp

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 listings
• realestate://all-agents: Agent directory
• realestate://market-overview: Current market trends
• realestate://all-areas: Area information
• realestate://amenities: Complete amenities database

Dynamic Resource Templates

• realestate://properties/area/{area}: Area-specific properties
• realestate://agent/{agent_id}/dashboard: Agent performance dashboard
• realestate://market/area/{area}: Area market analysis
• realestate://property/{property_id}/insights: Property insights
• realestate://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

1. Clone the repository:

   git clone https://github.com/agentic-ops/real-estate-mcp.git
   cd real-estate-mcp
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. 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 class
• PropertyFilter: 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:

1. Unit Tests: Add to tests/unit/ for core logic
2. Integration Tests: Add to appropriate tests/integration/test_*.py
3. Use Fixtures: Leverage existing fixtures in conftest.py
4. Mock External Dependencies: Use unittest.mock for isolation
5. Test Edge Cases: Include boundary conditions and error scenarios
6. Follow Naming Convention: test_*.py files, Test* classes, test_* methods

🛠️ Development

Adding New Tools

1. Choose appropriate category in tools/
2. Add tool function with @mcp.tool() decorator
3. Register in the category's register_*_tools() function
4. Import and call registration in main.py
5. Add Tests: Create corresponding tests in tests/integration/

Adding New Resources

1. Choose appropriate domain module in resources/ (property, agent, market, client, location)
2. Add resource function with @mcp.resource() decorator and URI pattern
3. Register in the domain's register_*_resources() function
4. Import and call registration in main.py
5. Add Tests: Include resource tests in tests/integration/test_resources.py

Adding New Prompts

1. Choose appropriate category in prompts/ (property, client, market, or agent)
2. Add prompt function with @mcp.prompt() decorator
3. Include parameter defaults and comprehensive instructions
4. Register in the category's register_*_prompts() function
5. Add Tests: Include prompt tests in tests/integration/test_prompts.py

Adding New Prompt Categories

1. Create new file in prompts/ directory (e.g., prompts/new_category_prompts.py)
2. Follow the existing pattern with register_new_category_prompts(mcp) function
3. Import and register in prompts/__init__.py
4. 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

1. Fork the repository
2. Create a feature branch
3. Add your component following the established patterns
4. Test thoroughly
5. 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