ATTOM MCP Server

| Area | Details |
|------|---------|
| Dual Transport | Exposes the same MCP interface over HTTP (for browsers/REST clients) and stdio (for AI tool runners). |
| Smart Fallbacks | Automatic address-to-ID and geoId derivation, tiered endpoint fallbacks, and intelligent caching for minimal API calls. |
| Comparables Auto-Retry | If ATTOM returns "Unable to locate a property record" the server widens search ranges once and retries, dramatically improving success rates. |
| Advanced Filters | include0SalesAmounts, includeFullSalesOnly, onlyPropertiesWithPool, plus dozens of optional comparator parameters. |
| Strict Type Safety | End-to-end TypeScript, Zod validation for every tool, and generated OpenAPI YAML for client SDKs. |
| Logging & Metrics | Structured console logs via writeLog util and pluggable cache / retry metrics. |
| Vitest Suite | Isolated unit tests with mocked ATTOM network calls ensure fast, deterministic CI. |

---

- Node 18+ (ES Modules support)
- ATTOM API Key (required)
- Google Maps API Key (optional – for address normalization)

This package offers the MCP Server interface for interacting with the ATTOM API functionality:

- Intended Use: Programmatic interaction, especially by AI agents or other MCP-compatible clients.
- How it Works: Launched via npm run mcp:stdio or npm run mcp:http. Exposes functionality through structured groupedTools (e.g., property_query, sales_query) requiring a kind parameter specifying the desired endpoint.
- Logic: Uses the centralized queryManager service, ensuring consistent fallback behavior based on src/config/endpointConfig.ts.

---

npm ci # reproducible installs

cp .env.example .env && $EDITOR .env # add keys
``

| Variable | Purpose | Example |
|----------|---------|---------|
| ATTOM_API_KEY | Required – auth token | 123abc... |
| ATTOM_API_BASE_URL | Override ATTOM host | https://api.gateway.attomdata.com |
| ATTOM_API_RETRIES | Network retry attempts | 2 |
| CACHE_TTL_DEFAULT | Seconds for in-mem cache | 3600 |
| GOOGLE_MAPS_API_KEY | Enable Places normalization | optional |
| PORT | HTTP server port | 3000` |

> Tip: The server never prints sensitive keys; all logs are sanitized.

---

The primary way to interact with the ATTOM API via the MCP Server interface is using the single attom_query tool defined in src/mcp/groupedTools.ts.

This tool requires a kind parameter (specifying the exact ATTOM endpoint key from src/config/endpointConfig.ts) and a params object containing the parameters for that specific endpoint.

Example Usage:

{
  "tool_name": "attom_query",
  "arguments": {
    "kind": "propertyBasicProfile",
    "params": {
      "address1": "123 Main St",
      "address2": "Anytown, CA 90210"
    }
  }
}

{
  "tool_name": "attom_query",
  "arguments": {
    "kind": "salesComparablesPropId",
    "params": {
      "propId": "123456789",
      "miles": 2
    }
  }
}

The kind parameter accepts any of the endpoint keys defined in src/config/endpointConfig.ts.

All registered tool metadata (summary, parameters, etc.) is exported to OpenAPI YAML (openapi/attom-api-schema.yaml), which can be generated using npm run gen:openapi.

---