realtystack-mcp

realtystack-mcp

RealtyStack API 向けのリモート MCP（Model Context Protocol） コネクターです。米国の不動産データを RentCast 上に構築しており、不動産レコードの検索と単一レコードの照会、比較対象を含むAVM売却価格および長期賃料の推定、販売中・賃貸中の物件情報を、単一のフラットな /v1 JSON コントラクトで提供します。

上流： https://realestate-api-kappa.vercel.app（RealtyStack REST API）— /v1 エンドポイントごとに1つ、合計6つのツールがあります。上流のデプロイは従量課金制（RapidAPI／Apify、およびそれ自体が従量課金制のRentCast割当量上に構築されています）のため、このコネクターではサーバー側のRapidAPIプロキシシークレット（REALTYSTACK_MCP_PROXY_SECRET。X-RapidAPI-Proxy-Secret ヘッダーとして送信）を使って外向きの呼び出しを認証し、IPごとのソフトなレート制限（REALTYSTACK_MCP_RATE_LIMIT。デフォルトは1時間あたり30回のツール呼び出し、メモリ内で管理）を適用します。これにより、この無料のMCPプランを、有料の物件情報を無制限に利用する抜け道ではなく、情報を探すための窓口として維持します。詳しくは lib/ratelimit.js を参照してください。

これは何か、なぜ独立したコネクターなのか

RealtyStackは一般的なREST APIです。どのHTTPクライアントからでも直接呼び出せます。このリポジトリが存在するのは、MCPクライアント（Claude、ChatGPT、その他のMCP対応エージェント）は任意のREST APIを利用せず、MCPツールを利用するためです。 realtystack-mcp は薄いアダプターレイヤーで、次の機能を提供します。

• RealtyStackの各 /v1 エンドポイントを、LLMが理解して直接呼び出せる、検出可能で型付けされたMCP ツール（名前、説明、zod入力スキーマ、アノテーション）として公開します。REST APIの構成を別途教える必要はありません。
• 単一の /mcp エンドポイントでMCPの ストリーミング可能なHTTP トランスポートを使用するため、URLひとつでClaude、ChatGPT、その他のMCPクライアントにコネクターとして登録できます。
• それ以外のことは行いません。独自のビジネスロジックはなく、すべてのツール呼び出しはRealtyStackへのパススルー fetch で、RealtyStackが返すJSONレスポンスをツールの結果としてそのまま返します。

認証：MCP呼び出し元側では不要（意図的な設計）

RealtyStackのデータには ユーザーごとの区別がありません。不動産レコード、評価額の推定、物件情報といった客観的な不動産データです。呼び出し元ごとにアクセスを制限する必要がないため、このコネクターには意図的に次の仕組みを設けていません。

• OAuth、ログイン、MCPクライアントからのベアラートークンはありません
• Supabase／データベースはありません
• デモ用と実データ用のアカウントの区別はありません。すべての呼び出し元に、同じ実データをリアルタイムで提供します

api/mcp.js はリクエストごとにステートレスな McpServer を新たに構築し、MCP呼び出し元の認証チェックなしで提供します。

上流の認証（外向きの呼び出し）

上流の RealtyStackデプロイでは、すべての /v1/* ルートにRapidAPIプロキシシークレットを要求します（realestate-api/src/guard.js を参照）。このコネクターは、REALTYSTACK_MCP_PROXY_SECRET 環境変数から読み込んだ同じシークレットを、外向きの fetch 呼び出しの X-RapidAPI-Proxy-Secret ヘッダーとして送信することで実データにアクセスします。動作確認済みです。X-RapidAPI-Proxy-Secret を送信するとガードを通過して実データが返り、何も送信しない場合は 403 "This API is served through RapidAPI." が返ります。これは上流の収益化に関する仕様であり、このコネクター自体に認証を追加するものではありません。設計上、引き続きMCP呼び出し元の認証は一切ありません。

ツール一覧

RealtyStack の /v1 エンドポイントごとに 1 つのツールを提供します（realestate-api/openapi.yaml を参照。/api/health は意図的にラップしていません）。

ツール	RealtyStack エンドポイント	説明
search_properties	GET /v1/properties	住所、市区町村／州／ZIP コード、または緯度／経度と半径で、構造に関するフィルターを指定して物件レコードを検索します。
get_property	GET /v1/properties/{id}	RentCast の ID を指定して、1 件の物件レコードの詳細を取得します。
avm_value	GET /v1/avm/value	AVM による売却価格の推定値（代表値と範囲）と、スコア付きの類似売却物件を取得します。
avm_rent	GET /v1/avm/rent	AVM による長期賃料の推定値（代表値と範囲）と、スコア付きの類似賃貸物件を取得します。
search_sale_listings	GET /v1/listings/sale	MLS およびエージェント／事務所の連絡先を含む、販売中（または販売終了）の物件リスティングを取得します。
search_rental_listings	GET /v1/listings/rental	賃貸中（または賃貸終了）の長期賃貸物件リスティングを取得します。

6 つのツールはいずれも読み取り専用の GET で、{ readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true } と注釈されています。どのツールもデータを書き込まず、すべて外部で変化するリアルタイムの不動産データを反映します。

realestate-api のラップ方法

各ツールハンドラーは、実際の RealtyStack REST API に対して fetch(\${REALTYSTACK_MCP_API_BASE_URL}${path}`, ...)を実行し（設定されている場合はX-RapidAPI-Proxy-Secret` ヘッダーを追加）、解析した JSON を MCP ツール結果のコンテンツとして返します。

{ content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }

上流の HTTP エラー（4xx／5xx）は捕捉され、リクエストをクラッシュさせるのではなく、asError ヘルパーを通じて型付きの MCP エラー結果として表示されます。

環境変数

変数	用途	デフォルト
REALTYSTACK_MCP_API_BASE_URL	上流 RealtyStack のベース URL	https://realestate-api-kappa.vercel.app
REALTYSTACK_MCP_PROXY_SECRET	上流のガードを通過するため、X-RapidAPI-Proxy-Secret として送信されます	（未設定の場合、ガードされた上流から 403 が返されます）
REALTYSTACK_MCP_RATE_LIMIT	IP ごとの 1 時間あたりのツール呼び出し上限（ソフト制限）	30

プロジェクト構成

api/mcp.js       MCP endpoint (StreamableHTTPServerTransport, stateless, no caller auth)
api/health.js    GET /api/health
lib/tools.js     All 6 tool definitions (zod schemas + fetch-and-forward handlers)
lib/ratelimit.js Soft in-memory per-IP tools/call cap
local-server.js  Plain-Node http server for local dev / smoke testing (not deployed)
test/smoke.mjs   Real end-to-end smoke test (initialize, tools/list, tools/call)
vercel.json      Routes /mcp -> api/mcp.js, /health -> api/health.js
server.json      MCP registry metadata

ローカル開発

npm install
npm run dev          # starts local-server.js on http://localhost:3900

ローカルのエンドポイント：POST http://localhost:3900/mcp、GET http://localhost:3900/health。

ローカルで実際の上流データにアクセスするには、プロキシシークレットを設定します。

REALTYSTACK_MCP_PROXY_SECRET=<secret> npm run dev

スモークテスト

npm run dev &                 # terminal 1
npm run smoke                 # terminal 2

test/smoke.mjs は、実際の HTTP／JSON-RPC 経由で実行中のサーバーを操作し、次の項目を検証します。

1. GET /health が { ok: true, ... } を返す
2. initialize が成功し、serverInfo.name === "realtystack" を報告する
3. tools/list が、Zod から生成された JSON スキーマとともに 6 つのツールすべてを返す
4. search_properties の tools/call により、ツールをエンドツーエンドで実行する（REALTYSTACK_MCP_PROXY_SECRET が設定されている場合は、実際の上流結果が返ることを検証します。未設定の場合もツール呼び出しの仕組みは確認され、上流が正直に返す 403 ガード応答も許容されます）

デプロイ

このビルドではデプロイされていません（先に確認してください）。確認後：

cd /Users/isaiahdupree/Software/realtystack-mcp
npx vercel --yes --prod

デプロイ後、Claude／ChatGPT／任意の MCP クライアントに登録する MCP コネクター URL は次のとおりです。

https://<deployment-domain>/mcp