Real Estate MCP

🚀 Real Estate MCP Server

A comprehensive Model Context Protocol (MCP) server for real estate data management, offering tools, resources, and prompts for property listings, agent management, market analysis, client relationships, and area intelligence.

🚀 Quick Start

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
   

✨ Features

MCP Capabilities

• 30+ Tools: Facilitate comprehensive real estate operations.
• 10 Resources: Comprising 5 static resources and 5 dynamic resource templates.
• 11 Prompts: User - controlled analysis templates across 4 categories.
• SSE Transport: A web - compatible Server - Sent Events endpoint.

Tool Categories

🏠 Property Management (7 tools)

• Search and filter properties based on multiple criteria.
• Retrieve property details and comprehensive insights.
• Provide area - based and agent - based property listings.
• Conduct market context and comparable analysis.

👥 Agent Operations (6 tools)

• Manage agent profiles and specializations.
• Offer performance dashboards and metrics.
• Handle client and property portfolio management.
• Track sales and perform analytics.

📊 Market Analysis (7 tools)

• Provide market overview and price analytics.
• Analyze area - specific market performance.
• Assess investment opportunities.
• Conduct comparative area analysis.
• Track transactions.

🤝 Client Management (3 tools)

• Manage client profiles and preferences.
• Implement property matching algorithms.
• Offer budget and criteria - based recommendations.

🏘️ Area Intelligence (9 tools)

• Generate comprehensive area reports.
• Provide amenities and demographics data.
• Offer data on schools, parks, shopping, and healthcare.
• Present city overview and area comparisons.

⚙️ System Management (2 tools)

• Manage data refresh and cache.
• Provide 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

The installation steps are as follows:

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
   

💻 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"}}}'

📚 Documentation

🏗️ 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/

🔍 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.

🧪 Testing

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

🛠️ 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