RE Data Refinery

RE Data Refinery MCP 服务

一个 MCP（Model Context Protocol）服务，为 AI Agent 提供实时访问俄亥俄州五大城市——哥伦布、辛辛那提、托莱多、代顿和克利夫兰——评分房地产投资数据的能力，数据涵盖房源、翻新转售/批发评分、租金收益率、止赎拍卖和税务拍卖房源。Agent 通过 MCP 工具查询数据，并使用 x402 微支付（Base 主网上的 USDC）按次付费。

功能

此服务提供 13 个 MCP 工具，供任何 AI Agent（Claude、Cursor、Hermes 等）使用：

• 搜索房源 — 查询 1,040 多处已评分的俄亥俄州房产，查看翻新转售评分、批发评分、租金收益率百分比、市场热度评级和社区比较。可按城市、ZIP 邮编、价格范围、评分门槛或房产类型筛选
• 获取房产详情 — 按 ZPID 获取完整房产记录，包括价格历史、税费/评估历史和学校评级
• 搜索止赎拍卖 — 192 条富兰克林县止赎房源，包含拍卖日期、地址、出售状态和地块面积（数据来自 PropertyOnion，每日刷新）
• 搜索税务拍卖 — 161 条富兰克林县税务拍卖房源，结构相同
• 查询综合拍卖 — 一次调用获取全部 353 条拍卖房源，可按城市、ZIP 邮编、状态或类型筛选

所有付费查询均使用 x402 协议——Agent 在 Base 主网上发送 USDC 微支付（每次查询 $0.15–$0.50），即可获取数据。无需订阅，也无需 API 密钥——只需通过加密货币按次付费。

数据来源

来源	数据	覆盖范围
ZillAPI	房源、评分、价格/税费/学校历史	哥伦布、辛辛那提、托莱多、代顿和克利夫兰的 1,040 处已评分房产
PropertyOnion	止赎 + 税务拍卖房源	富兰克林县 353 条房源（每日刷新）
Franklin County GIS	欠税、许可证、分区	数据增强层（持续更新）

各城市房产数量

城市	已评分房产
哥伦布	184
辛辛那提	200
托莱多	200
代顿	200
克利夫兰	256
总计	1,040

工具

工具	描述
refinery_health	API 状态 + 缓存的房产数量（免费）
refinery_cache_stats	缓存新鲜度 + 城市/社区数量（免费）
refinery_credits	ZillAPI 额度余额（免费）
refinery_payment_status	x402 支付配置状态（免费）
refinery_search_properties	带评分的房产搜索结果（多城市）。每次调用 $0.50
refinery_list_properties	所有已缓存房产及其翻新转售/批发/租金评分。每次调用 $0.35
refinery_get_property	按 ZPID 获取完整房产详情。每次调用 $0.35
refinery_get_price_history	房产价格历史。每次调用 $0.25
refinery_get_tax_history	房产税费/评估历史。每次调用 $0.25
refinery_get_schools	房产附近的学校评级。每次调用 $0.25
refinery_search_foreclosures	192 条止赎拍卖房源。每次调用 $0.15
refinery_search_tax_sales	161 条税务拍卖房源。每次调用 $0.15
refinery_search_auctions	合并查询全部 353 条拍卖房源。每次调用 $0.25

设置

cd ~/projects/re-refinery/mcp-server
uv sync

环境变量

在此目录中创建 .env：

# Optional: override the worker or local API URLs
REFINERY_BASE_URL=https://re-data-refinery.ares-hms.workers.dev
REFINERY_LOCAL_URL=http://localhost:5004

# Required for paid x402 endpoints
EVM_PRIVATE_KEY=0x...

# Optional x402 spend cap (default $1 per payment)
X402_SPEND_CAP=$1

# Set to false to disable payments and use the free local API
REFINERY_ENABLE_X402=true

运行

# stdio transport (default; for Claude Desktop, Hermes, etc.)
uv run python re_refinery_mcp.py

# SSE transport
uv run python re_refinery_mcp.py --transport sse

MCP 配置

将以下内容添加到 MCP 客户端配置中（Claude Desktop 的 claude_desktop_config.json、Cursor 等）：

{
  "mcpServers": {
    "re-refinery-mcp": {
      "command": "uv",
      "args": ["run", "python", "re_refinery_mcp.py"],
      "cwd": "/path/to/re-refinery-mcp"
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "re-refinery-mcp": {
      "command": "uv",
      "args": ["run", "python", "re_refinery_mcp.py"],
      "cwd": "/path/to/re-refinery-mcp",
      "env": {
        "REFINERY_BASE_URL": "https://re-data-refinery.ares-hms.workers.dev",
        "REFINERY_ENABLE_X402": "true",
        "EVM_PRIVATE_KEY": "0x..."
      }
    }
  }
}

使用 MCP Inspector 测试

npx @modelcontextprotocol/inspector \
  uv run python /Users/ares.hmsgmail.com/projects/re-refinery/mcp-server/re_refinery_mcp.py

Hermes 配置

在 ~/.hermes/config.yaml 的 mcp_servers: 下添加：

re_refinery:
  enabled: true
  command: /Users/ares.hmsgmail.com/projects/re-refinery/mcp-server/.venv/bin/python
  args:
    - /Users/ares.hmsgmail.com/projects/re-refinery/mcp-server/re_refinery_mcp.py
  timeout: 120

备注

• 此服务为只读服务；没有工具会创建或修改属性。
• 所有付费工具都支持 response_format: "json"，可输出机器可读的内容。
• 如果缺少 EVM_PRIVATE_KEY 且已启用 x402，服务仍会启动，但付费调用会返回清晰的 402 错误消息。