propraven

@propraven/mcp

PropRaven 用の Model Context Protocol サーバーです。Claude、ChatGPT、Cursor、および MCP 互換のあらゆるエージェントに、所有者情報、評価額、許可証、権利証書、災害リスク、市場データを含む、米国の 1 億 9,130 万件の地番（うち 1 億 1,000 万件は地図に表示済み）への標準的なアクセスを提供します。

ホスト型エンドポイント： **https://propraven.com/mcp**（Streamable HTTP、インストール不要 — ドキュメント：https://propraven.com/docs/mcp · エージェント + x402：https://propraven.com/docs/agents）。または、以下の手順で stdio サーバーをローカルで実行できます。

---

ホスト型（インストール不要）

HTTP トランスポート対応の MCP クライアントから、API キーを Bearer ヘッダーとして指定して https://propraven.com/mcp に接続します。Claude Desktop / Cursor（claude_desktop_config.json、~/.cursor/mcp.json）：

{
  "mcpServers": {
    "propraven": {
      "url": "https://propraven.com/mcp",
      "headers": { "Authorization": "Bearer pz_your_real_key_here" }
    }
  }
}

Claude Code の場合：claude mcp add --transport http propraven https://propraven.com/mcp --header "Authorization: Bearer pz_your_real_key_here"。 claude.ai の Web コネクターでは代わりに OAuth を使用します。同じ URL でカスタムコネクターを追加し、サインインしてください。

---

ローカル stdio サーバー（npx @propraven/mcp）

要件： Node ≥18、https://propraven.com/settings/api-keys から取得した PropRaven API キー（pz_…）（無料、カード不要）。

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）を編集します。

{
  "mcpServers": {
    "propraven": {
      "command": "npx",
      "args": ["-y", "@propraven/mcp"],
      "env": { "PROPRAVEN_API_KEY": "pz_your_real_key_here" }
    }
  }
}

Cursor（~/.cursor/mcp.json）でも同じブロックを使用します。Claude Code の場合： claude mcp add propraven --env PROPRAVEN_API_KEY=pz_your_real_key_here -- npx -y @propraven/mcp。

クライアントを再起動します。8 つの PropRaven ツールがツール一覧に表示されます。

クイックテスト

Look up parcel 37:119:12104406 and tell me the owner.

エージェントは parcel_lookup を選択し、所有者を含む標準的な地番カードを返すはずです。

ChatGPT： カスタム GPT → アクション → OpenAPI URL https://api.propraven.com/openapi.json を指定し、API キー（Bearer）認証を設定します。ChatGPT のネイティブ MCP は、ホスト型エンドポイント https://propraven.com/mcp を使用できます（OAuth 2.1 + PKCE）。

---

ツール

名前はホスト型サーバーに一致します（MCP クライアントと Anthropic API が要求する ^[a-zA-Z0-9_-]{1,64}$）。

ツール	用途	バックエンド
parcel_lookup	ID、住所、または APN で区画を 1 件検索します	GET /api/v1/parcels/{id}（ID）または GET /api/v1/search/full（住所／APN）
parcel_search	所有者、住所の一部、APN、または市区町村でテキスト検索します（州／市区町村フィルター、キーセット cursor に対応）	GET /api/v1/search/full
parcel_compare	エージェント側でのランキング向けに、2～25 件の区画カード（ハザード情報付き）を無料で取得します	GET /api/v1/parcels/{id}（＋/risks）× N
owner_pierce	所有者名義の区画を取得します（任意の state フィルター、ベストエフォートの ticker）	GET /api/v1/owners/{name}/portfolio（ticker には /owners/search を使用）
hazard_score	洪水／山火事／地震／暴風／大気質／犯罪の各ブロック	GET /api/v1/parcels/{id}/risks
valuation_estimate	市場価値、AVM、評価額、直近の売却、平方フィートあたりの価格	GET /api/v1/parcels/{id}
permits_history	許可の履歴（新しいものから最大 100 件、実際の件数を含む）	GET /api/v1/parcels/{id}/permits?shape=envelope
sales_history	権利証／所有権移転の履歴	GET /api/v1/parcels/{id}/deeds?shape=envelope

区画 ID。 正規の形式は state_fips:county_fips:parcel_id です。例：37:119:12104406。従来の 5 桁形式（37119:12104406）と PropRaven の区画 UUID も受け付けます。parcel_search と parcel_lookup の住所検索では、各結果に lookup_id が追加されます（検索結果の parcel_id には PropRaven UUID が含まれます）。この ID は parcel_lookup／parcel_compare で使用できます。

どのツールも料金を支払いません。 クライアントは上記の無料／従量制読み取りエンドポイント 7 つにのみ GET を送信し、リクエスト送信前にそれ以外のすべてのパス（有料の区画レポート、比較物件パック、リスクスコア、所有者レポート、リード、ストアフロントなど）を拒否し、支払いヘッダーを送信することもありません。API が x402 402 Payment Required を返した場合、ツールは 402 payment required — this tool never pays を返します。呼び出しは引き続きプランの月間クォータにカウントされます。物件調査資料を購入するには、ホスト型サーバーの明示的な buy_* ツールまたは propraven.com を使用してください。

エラーは RFC 7807 の問題詳細で、<status> <code>: <detail> として表示されます（例：404 not_found: …）。Retry-After が 10 秒以下の場合、429 または 503 は 1 回再試行されます。

ツールの説明には、各ツールを使用しない状況が記載されています。これはエージェントの選択精度を左右する最大の要因です。

---

環境

変数	デフォルト	用途
PROPRAVEN_API_KEY	(必須)	ベアラートークン、形式は pz_...
PROPRAVEN_BASE_URL	https://propraven.com	API ホスト（すべてのパスは /api/v1 で始まります）。
PROPRAVEN_TIMEOUT_MS	30000	リクエストごとのタイムアウト（ミリ秒）。

リクエストには User-Agent: @propraven/mcp/<version> が含まれます。

---

開発／検査

npm ci
npm run build
npm test          # node:test suite — no network, no API key needed

# Live-reloading dev (TypeScript, no build step):
PROPRAVEN_API_KEY=pz_test... npm run dev

# Or open the MCP Inspector UI:
PROPRAVEN_API_KEY=pz_test... npm run inspect

https://modelcontextprotocol.io/legacy/tools/inspector のインスペクターでは、各ツールを手動で呼び出し、リクエスト／レスポンスのペイロードを確認できます。

---

このプロジェクトの目的

不動産データを扱う Claude／ChatGPT／Cursor のすべてのワークフローには、信頼できる区画検索ツールが必要です。現在、標準となる不動産データ MCP はありません。PropRaven は、先行者利益を得られる期間が終わる前（約 12～18 か月以内）に、その標準となることを目指しています。

---

ライセンス

Apache-2.0