Skip to main content
Glama
david-pivonka

constellation1-mcp-server

by david-pivonka
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

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

Related MCP server: Repliers MCP Server

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 LICENSE file for details.

Available Tools

2 tools
reso_helpA

Get comprehensive RESO field reference documentation, query examples, and best practices. This tool provides instant access to field guides, entity descriptions, filter patterns, and common use cases for effective RESO API usage.

ParametersJSON Schema
NameRequiredDescriptionDefault
topicYesHelp topic to retrieve. Options: entities, fields, filters, enums, expand, examples, performance, images, metadata, overview

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden of explaining behavior. It does convey that the tool returns documentation and reference content rather than performing mutations or executing queries. However, it does not disclose details like whether it returns one topic at a time, how output is formatted, or any limitations such as lack of rate limits or auth requirements. For a simple help tool, this is adequate but not richly transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short, but the two sentences are somewhat redundant: 'RESO field reference documentation, query examples, and best practices' overlaps with 'field guides, entity descriptions, filter patterns, and common use cases.' Phrases like 'instant access' and 'effective RESO API usage' are filler rather than informative. It could be tighter without losing meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with a single enum parameter and no output schema, the description provides enough context to understand what the tool returns and its general scope. It covers the purpose and content areas, while the schema fully enumerates the selectable topics. It does not explain return structure, but that is less critical given the simple, documentation-oriented nature of the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage and enumerates all valid topics with a clear enum. The description adds general context about what kinds of help are available but does not meaningfully expand on individual parameter semantics beyond what the schema already provides. Baseline of 3 is appropriate because the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool as a reference/help resource for RESO: 'Get comprehensive RESO field reference documentation, query examples, and best practices.' The verb 'Get' plus the specific resource type makes the purpose concrete, and it is naturally distinguished from the sibling reso_query, which presumably executes queries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool should be used when the agent needs RESO documentation, examples, or best practices, but it does not explicitly state when to choose this tool over reso_query. There is no direct 'use this when...' or 'use reso_query instead for...' guidance, leaving the usage context to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

reso_queryB

Query the RESO (Real Estate Standards Organization) API for comprehensive real estate data. This tool provides access to MLS (Multiple Listing Service) data including property listings, agent information, office details, media files, and market analytics. Perfect for real estate research, market analysis, property searches, and lead generation. Supports advanced filtering, sorting, and field selection with standardized RESO field names for consistent data access across different MLS systems.

ParametersJSON Schema
NameRequiredDescriptionDefault
topNoMaximum number of records to return (1-1000). Use 10-50 for quick searches, 100-1000 for analysis.
skipNoNumber of records to skip for pagination. Skip limits: Property (1M), Office/Member (500K), Media (50K)
entityNoRESO Entity to query. Options: Property (listings), Member (agents), Office (brokerages), Media (photos/videos), OpenHouse (events), Dom (days on market), PropertyRooms (room details), PropertyUnitTypes (unit info), RawMlsProperty (raw MLS data)
expandNoInclude related entities. Examples: "Media", "Media($filter=Permission ne 'Private')", "Media,OpenHouse,Dom"
filterNoOData filter expression. Examples: "StandardStatus eq 'Active'", "ListPrice ge 200000 and ListPrice le 500000", "City eq 'Seattle'"
selectNoComma-separated list of fields to return. Leave empty to get all available fields. Common Property fields: ListingKey, StandardStatus, ListPrice, BedroomsTotal, City, PublicRemarks
orderbyNoSort order. Format: "FieldName [asc|desc]". Examples: "ListPrice desc", "City asc, ModificationTimestamp desc"
nextLinkNoUse @odata.nextLink URL from a previous query response to get the next page of results. When provided, other parameters (except ignorenulls/ignorecase) are ignored. This enables efficient server-side pagination for large result sets. Example: use the @odata.nextLink value from a previous reso_query response.
ignorecaseNoEnable case-insensitive text matching for filters. Default: false.
ignorenullsNoExclude null/empty fields to reduce payload size. Default: true.

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden, but it only says 'Query' and 'data access.' It does not explicitly state the operation is read-only, mention authentication/rate-limit implications, or clarify how nextLink/pagination behaves, which is important for a 10-parameter API tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, but contains filler phrases like 'Perfect for' and 'comprehensive' and repeats the MLS/RESO concept across multiple sentences. It is acceptable but not tightly edited.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The rich input schema covers parameters, but there is no output schema and the description does not describe response shape, pagination behavior, or how results are returned. It identifies data categories and use cases, making it minimally adequate for a query tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents every parameter. The description adds high-level color about filtering, sorting, and field selection, but does not provide significant meaning beyond the schema, meriting the baseline score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the action ('Query the RESO API') and the resource domain (MLS property, agent, office, media, and analytics data), making the tool's purpose easy to grasp. It does not explicitly distinguish itself from the sibling reso_help, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It offers broad intended-use context ('Perfect for real estate research, market analysis, property searches, and lead generation') but no explicit conditions for when to use this tool instead of reso_help, nor any exclusions. The guidance is implied rather than prescriptive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.0.0-dev
    • First observedreso_help
    • First observedreso_query
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored across 2 tools

Disambiguation5/5

reso_query is the execution tool for actual data retrieval and filtering, while reso_help provides documentation, field references, and query examples. There is no functional overlap, so an agent can clearly choose between acting and learning.

Naming Consistency5/5

Both tools use the consistent reso_ prefix followed by a clear action word, creating a predictable pattern. Even though the set is small, the naming is uniform and easy to infer.

Tool Count3/5

Two tools is a minimal surface for a broad RESO API domain. Both tools earn their place, but the server feels slightly thin rather than fully fleshed out for the range of data it claims to access.

Completeness5/5

The read-only query workflow is well covered: reso_query handles all entity searches, filtering, sorting, and field selection, while reso_help provides the necessary reference and examples. There are no obvious missing operations for the stated purpose.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • UNLOCK MLS RESO Reference MCP

    GumpperGroup
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI applications to search and analyze UNLOCK MLS real estate data through Bridge Interactive's RESO Web API, supporting natural language property searches, market analysis, and agent discovery.
    2
    -

  • Repliers MCP Server

    mickmath86
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides tools to access the Repliers API for real estate listings, property search, market analytics, and AI-powered data through natural language queries.
    205 npm
    MIT
  • Repliers MCP Server by Repliers-io

    Repliers MCP Serverofficial

    Repliers-io
    A
    license
    Not graded
    quality
    B
    maintenance
    Provides AI assistants access to real-time MLS data via the Repliers API, enabling natural language property search, market statistics, and listing details.
    205 npm
    17
    MIT