ATTOM API MCP Server

ATTOM API MCP 服务

一个适用于 ATTOM API 的 MCP 服务，通过 MCP 协议提供房地产数据。该服务充当中间件，将 ATTOM API 端点作为 MCP 工具开放，供 AI Agent 使用。

功能

• 为 ATTOM API 端点提供 MCP 接口
• 全面覆盖房产数据、估值、评估和销售相关 API
• 结构化错误处理和日志记录
• 可通过环境变量配置
• 打包为 Python CLI 工具，便于部署

前置条件

• Python 3.11 或更高版本
• 用于管理依赖项的 uv
• ATTOM API 密钥

安装

使用 UVX（推荐）

安装和运行 ATTOM API MCP 服务的最简单方式是使用 uvx：

uvx mcp-server-attom --help

这会直接下载并运行工具，无需永久安装。

如需永久安装：

uv tool install mcp-server-attom

本地开发

1. 克隆此仓库：

git clone https://github.com/nkbud/mcp-server-attom.git
cd mcp-server-attom

2. 安装依赖项：

uv sync --locked --all-extras --dev

3. 创建 .env 文件并填入 ATTOM API 密钥：

cp .env.example .env
# Edit .env and add your ATTOM API key

用法

MCP 客户端集成

有关在各种 MCP 客户端（Claude Desktop、mcp-inspector、mcp-cli）中使用此服务以及通过 stdio 通信的详细说明，请参阅客户端集成指南。

快速入门示例：

# With Claude Desktop - add to configuration file
{
  "mcpServers": {
    "attom-api": {
      "command": "uvx",
      "args": ["mcp-server-attom"],
      "env": {"ATTOM_API_KEY": "your_api_key_here"}
    }
  }
}

# With MCP Inspector
npx @modelcontextprotocol/inspector uvx mcp-server-attom

# With MCP CLI
mcp list tools uvx mcp-server-attom
mcp call uvx mcp-server-attom property_detail '{"attom_id": "145423726"}'

# Direct stdio communication
export ATTOM_API_KEY=your_api_key_here
uvx mcp-server-attom

作为 CLI 工具运行

使用 mcp-server-attom 命令启动服务：

# If installed via uv tool install
mcp-server-attom --port 8000 --host 0.0.0.0

# Or run directly via uvx
uvx mcp-server-attom --port 8000 --host 0.0.0.0

可用的命令行选项：

• --host：服务绑定的主机（默认值：0.0.0.0）
• --port：服务绑定的端口（默认值：8000）
• --log-level：日志级别（debug、info、warning、error）
• --reload：代码更改时启用自动重新加载

在开发期间本地运行

在开发期间启动服务：

python -m src.server

这会启动服务，并使用 stdio 传输进行 MCP 通信。

发起请求

该服务为各种 ATTOM API 端点提供 MCP 工具。下面以使用 property_detail 工具为例：

await mcp.tools.property_detail(
    attom_id="145423726"  # OR
    # address="123 Main St, New York, NY 10001"  # OR
    # address1="123 Main St", address2="New York, NY 10001"  # OR
    # fips="36061", apn="12345"
)

配置

可使用以下环境变量配置服务：

变量	描述	必需	默认值
ATTOM_API_KEY	你的 ATTOM API 密钥	是	-
ATTOM_HOST_URL	ATTOM API 的基础 URL	否	https://api.gateway.attomdata.com
ATTOM_PROP_API_PREFIX	房产 API 端点的前缀	否	/propertyapi/v1.0.0
ATTOM_DLP_V2_PREFIX	DLP v2 API 端点的前缀	否	/property/v2
ATTOM_DLP_V3_PREFIX	DLP v3 API 端点的前缀	否	/property/v3
LOG_LEVEL	日志级别（DEBUG、INFO、WARNING、ERROR）	否	INFO
LOG_FORMAT	日志格式（json 或 console）	否	json

可用工具

此 MCP 服务全面覆盖 ATTOM Data API，包含所有主要类别中的 55+ 个端点。有关详细的 API 覆盖映射，请参阅 ATTOM_API_COVERAGE.md。

核心类别

• 房产工具（14 个端点）：地址查询、房产详情、档案、建筑许可、销售历史
• 评估工具（3 个端点）：评估详情、快照和历史记录
• 销售工具（6 个端点）：销售详情、历史记录、可比房产和趋势分析
• 估值工具（6 个端点）：AVM 数据、房屋净值、租赁估值
• 区域与位置工具（8 个端点）：地理边界、层级查询、CBSA 数据
• POI 工具（2 个端点）：兴趣点搜索，涵盖 14+ 个商业类别
• 社区工具（1 个端点）：全面的社区数据（犯罪、人口、教育、天气、通勤时间）
• 学校工具（3 个端点）：学校档案、学区和搜索功能
• 事件工具（2 个端点）：房产事件和快照
• 实用工具（3 个端点）：字段定义、交通噪声、止赎前数据

工具参数

所有与房产相关的工具都支持多种识别方式：

• AttomID：房产的直接标识符
• Address：完整的房产地址字符串
• Address1 + Address2：拆分的地址格式（街道 + 城市/州/邮编）
• FIPS + APN：县 FIPS 代码 + 评估员地块编号

区域和位置工具支持地理标识符：

• GeoIDv4：第 4 版地理标识符
• Latitude/Longitude：基于坐标的搜索
• WKT Strings：众所周知文本几何表示
• Radius：基于位置的查询搜索半径

开发

运行测试

uv run pytest

代码检查

uv run ruff check .
uv run black .
uv run isort .

构建和发布

将软件包构建并发布到 PyPI：

1. 确保你使用的是最新版本的 uv：

pip install -U uv

2. 设置 PyPI 令牌：

   • 如果你还没有账户，请在 PyPI 上创建一个
   • 前往“账户设置”>“API 令牌”
   • 创建一个范围限制为 mcp-server-attom 项目的令牌
   • 安全地保存令牌

3. 构建软件包：

uv build --no-sources

4. 使用你的 PyPI 令牌发布软件包：

uv publish --token YOUR_PYPI_TOKEN

或者，你也可以将令牌存储在 .pypirc 文件中，或将其设为环境变量：

export PYPI_TOKEN=YOUR_PYPI_TOKEN
uv publish

许可证

MIT

支持

如果此 MCP 服务有问题，请在 GitHub 仓库中提交 issue。

如果 ATTOM API 本身有问题，请联系 ATTOM Data Solutions 支持团队。