constellation1-mcp-server

Constellation 1 MCP Server

A Model Context Protocol (MCP) server that provides comprehensive access to Constellation 1 real estate data APIs. This server enables LLMs to perform property searches, agent research, market analysis, and media retrieval through RESO (Real Estate Standards Organization) standardized interfaces.

Features

• 🏠 Comprehensive Real Estate Data - Access to Properties, Agents, Offices, Media, and Market Analytics
• 🔍 Advanced Property Search - Full OData querying with filtering, sorting, and field selection
• 🤝 Agent & Office Discovery - Complete MLS member and brokerage information
• 📸 Media & Marketing Assets - Property photos, videos, virtual tours, and documents
• 📊 Market Analytics - Days on market, pricing trends, and historical data
• 🔐 Enterprise Security - OAuth2 authentication with automatic token management
• 📚 Rich Resources - Built-in field reference and query examples accessible via MCP
• ⚡ Performance Optimized - Dynamic metadata parsing, intelligent caching, and response optimization

Quick Start

1. Get Constellation 1 API Credentials

• Contact your RESO API provider to obtain Constellation 1 API access
• Obtain your client credentials (client_id and client_secret)
• Ensure you have access to the required RESO endpoints

2. Configure MCP Client

Add the server to your MCP client configuration:

Cursor

Add to your Cursor MCP settings (~/.cursor/mcp.json or through Command Palette > Open MCP Settings > New MCP Server):

{
  "mcpServers": {
    "constellation1": {
      "command": "npx",
      "args": ["-y", "constellation1-mcp-server"],
      "env": {
        "CONSTELLATION1_CLIENT_ID": "your-client-id-here",
        "CONSTELLATION1_CLIENT_SECRET": "your-client-secret-here"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "constellation1": {
      "command": "npx",
      "args": ["constellation1-mcp-server"],
      "env": {
        "CONSTELLATION1_CLIENT_ID": "your-client-id-here",
        "CONSTELLATION1_CLIENT_SECRET": "your-client-secret-here"
      }
    }
  }
}

Other MCP Clients

# Set environment variables
export CONSTELLATION1_CLIENT_ID="your-client-id-here"
export CONSTELLATION1_CLIENT_SECRET="your-client-secret-here"

# Run the server
npx constellation1-mcp-server

Available Tools

Real Estate Data

• reso_query - Query RESO entities with full OData support
• reso_help - Get field references, examples, and best practices

Usage Examples

Find Active Properties in Seattle

{
  "tool": "reso_query",
  "arguments": {
    "entity": "Property",
    "filter": "StandardStatus eq 'Active' and City eq 'Seattle'",
    "select": "ListingKey,ListPrice,BedroomsTotal,BathroomsTotal,UnparsedAddress,PublicRemarks",
    "orderby": "ListPrice asc",
    "top": 25
  }
}

Get Property with Marketing Photos

{
  "tool": "reso_query",
  "arguments": {
    "entity": "Property",
    "filter": "StandardStatus eq 'Active' and PhotosCount gt 0",
    "expand": "Media($filter=MediaCategory eq 'Photo' and Permission ne 'Private';$orderby=Order asc;$top=5)",
    "select": "ListingKey,ListPrice,UnparsedAddress,PhotosCount",
    "top": 10
  }
}

Find Real Estate Agent

{
  "tool": "reso_query",
  "arguments": {
    "entity": "Member",
    "filter": "MemberFullName eq 'John Smith'",
    "select": "MemberMlsId,MemberFullName,MemberEmail,MemberDirectPhone,OfficeName,MemberDesignation"
  }
}

Get Market Analysis Data

{
  "tool": "reso_query",
  "arguments": {
    "entity": "Property",
    "filter": "StandardStatus eq 'Closed' and CloseDate ge 2024-01-01",
    "select": "ListingKey,ClosePrice,CloseDate,BedroomsTotal,LivingArea,City,DaysOnMarket",
    "orderby": "CloseDate desc",
    "top": 100
  }
}

Get Help and Examples

{
  "tool": "reso_help",
  "arguments": {
    "topic": "examples"
  }
}

Configuration

Environment Variables

• CONSTELLATION1_CLIENT_ID (required) - Your Constellation 1 OAuth client ID
• CONSTELLATION1_CLIENT_SECRET (required) - Your Constellation 1 OAuth client secret

Optional Configuration

• CONSTELLATION1_BASE_URL (optional, default: https://listings.cdatalabs.com/odata) - API base URL
• CONSTELLATION1_AUTH_URL (optional, default: https://authenticate.constellation1apis.com/oauth2/token) - OAuth token endpoint

Alternative Environment Variable Names

The server also supports these alternative environment variable names:

• CLIENT_ID / CLIENT_SECRET
• RESO_CLIENT_ID / RESO_CLIENT_SECRET

API Quotas and Usage

This server accesses RESO-compliant real estate data through the Constellation 1 API. Monitor your API usage and ensure compliance with your RESO API provider's terms of service.

Resources

The server provides built-in MCP resources with documentation and examples:

• constellation1://docs/field-reference - Comprehensive RESO field reference guide
• constellation1://docs/quick-start - Common query patterns and examples

Access these through your MCP client's resource interface.

Error Handling

The server returns structured errors with helpful context:

{
  "error": {
    "code": "AUTH_FAILED",
    "message": "OAuth2 authentication failed: 401 Unauthorized",
    "context": {
      "endpoint": "https://authenticate.constellation1apis.com/oauth2/token",
      "status": 401
    }
  }
}

Common error codes:

• INVALID_ENTITY - Unsupported RESO entity type
• AUTH_FAILED - OAuth2 authentication failed
• API_ERROR - RESO API request failed
• SKIP_LIMIT_EXCEEDED - Pagination skip limit exceeded
• METADATA_FETCH_FAILED - Unable to load RESO metadata

Security

• API credentials are never logged or exposed in responses
• Input validation prevents injection attacks through Zod schemas
• OAuth2 tokens are securely cached and automatically refreshed
• All API communication uses HTTPS with proper certificate validation

Development

Building from Source

git clone https://github.com/david-pivonka/constellation1-mcp-server.git
cd constellation1-mcp-server
npm install
npm run build

Testing

npm test

Using MCP Inspector

npm run build

CONSTELLATION1_CLIENT_ID="your-client-id" CONSTELLATION1_CLIENT_SECRET="your-client-secret" npx @modelcontextprotocol/inspector ./dist/index.js

Contributing

Contributions are welcome! Please submit pull requests to our GitHub repository.

License

MIT License - see LICENSE file for details.