constellation1-mcp-server

david-pivonka/constellation1-mcp-server

3.2

If you are the rightful owner of constellation1-mcp-server 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.

Constellation 1 MCP Server provides access to comprehensive real estate data APIs, enabling LLMs to perform various real estate-related tasks through standardized interfaces.

Tools
2
Resources
0
Prompts
0

Constellation 1 MCP Server

npm version License: MIT

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

  1. Contact your RESO API provider to obtain Constellation 1 API access
  2. Obtain your client credentials (client_id and client_secret)
  3. 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 file for details.