# Moody's CRE MCP Server

MCP server for the Moody's Commercial Real Estate (CRE) API v3. Provides 37 tools for property lookups, market analytics, comps, CMBS data, tax records, and more.

## Setup

### 1. Configure credentials

Create a `.env` file in the project root:

```
CRE_EMAIL=your-email@example.com
CRE_API_KEY=your-api-key-here
```

### 2. Install dependencies

```bash
pip install -r requirements.txt
```

### 3. Run the server

**stdio mode** (default, for Claude Code / Claude Desktop):
```bash
python server.py
```

**HTTP mode** (for remote/web access):
```bash
MCP_TRANSPORT=http PORT=3000 python server.py
```

### 4. Add to Claude Code

Add to your Claude Code MCP settings (`claude mcp add`):

```json
{
  "mcpServers": {
    "cre": {
      "command": "python",
      "args": ["C:/Users/khano3/cre-mcp/server.py"],
      "env": {
        "CRE_EMAIL": "your-email@example.com",
        "CRE_API_KEY": "your-api-key"
      }
    }
  }
}
```

Or with Docker:
```bash
docker build -t cre-mcp .
docker run -it cre-mcp
```

---

## Tools Reference

### Typical Workflow

1. **Find a property** -> `search_properties` (returns `propertyKey`)
2. **Get property details** -> `get_property`, `get_amenities`, `get_unitmix`
3. **Get comps** -> `get_sales_comps`, `get_rent_comps`, `get_new_construction_comps`
4. **Get transaction data** -> `get_sales_history`, `get_recent_sale`, `get_listings`, `get_leases`
5. **Get analytics** -> `get_performance`, `get_cls`, `get_contacts`
6. **Get CMBS data** -> `get_cmbs_valuations`, `get_cmbs_loans`
7. **Get tax data** -> `get_tax_history`, `get_deed` (requires parcel FIPS + APN)
8. **Market analysis** -> `get_markets` -> `get_market_trends`, `get_market_overview`, etc.

---

### Property Tools

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `search_properties` | Search by address. Returns `propertyKey`. | `street`, `city`, `state`, `zip` |
| `get_property` | Full property attributes by key. | `property_key` |
| `get_property_by_parcel` | Look up by parcel FIPS + APN. | `parcel_fips`, `parcel_apn` |
| `bulk_property_lookup` | Bulk lookup by metro/zip + category. | `metrocode`, `category`, `zip`, `submarket_id`, `page_num`, `page_length` |
| `get_amenities` | Amenity data for a property. | `property_key` |
| `get_unitmix` | Unit mix (bedrooms, rents, sizes). | `property_key` |
| `entity_resolution` | Match a property by address or lat/long. | `street`, `city`, `state`, `zip`, `lat`, `long` |

### Comps Tools

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_sales_comps` | Sales comparables. | `property_key` or `lat`/`long`/`radius` or address fields. Filters: `category`, `building_class`, `total_price_min`/`max`, `size_building_sf_min`/`max`, `date_sold_start`/`end` |
| `get_rent_comps` | Rent comparables. | Same location params. Filters: `category`, `building_class`, `building_status` |
| `get_new_construction_comps` | New construction comparables. | Same location params + filters |

### Sales, Leases & Listings

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_sales_history` | Full sales history for a property. | `property_key` |
| `get_recent_sale` | Most recent sale. | `property_key` |
| `get_listings` | Active listings. | `property_key` |
| `get_leases` | Lease details for a listed space. | `listed_space_key` (from `get_listings`) |

### Performance, Contacts & CLS

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_performance` | Rent performance history. | `property_key` |
| `get_contacts` | Owners, managers, etc. | `property_key` |
| `get_cls` | Commercial Location Score. | `property_key` |

### CMBS

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_cmbs_valuations` | CMBS valuations summary. | `property_key` |
| `get_cmbs_loans` | CMBS loan data. | `property_key` |

### Tax & Deed

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_tax_history` | Tax history by parcel. | `parcel_fips`, `parcel_apn` |
| `get_tax_assessment_history` | Assessment history. | `parcel_fips`, `parcel_apn` |
| `get_tax_assessment_details` | Detailed assessment. | `parcel_fips`, `parcel_apn` |
| `get_deed` | Deed/ownership info. | `parcel_fips`, `parcel_apn` |

### Market Tools

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_markets` | List all metro markets. | `sector_id` (optional) |
| `get_market_trends` | Historical vacancy, rent, absorption. | `metro_id`, `sector_id`, `frequency` ("Yearly"/"Quarterly") |
| `get_market_overview` | Latest market snapshot. | `metro_id`, `sector_id`, `frequency` |
| `get_executive_briefing` | AI-generated market narrative. | `msa`, `sector`, `publication_frequency`, `subid` |
| `get_market_demographics` | Population, employment, etc. | `metro_id`, `frequency` |
| `get_transaction_analytics` | Sales transaction analytics. | `metro_id`, `sector_id`, `building_class` |
| `get_market_vintage` | Vintage performance data. | `metro_id`, `sector_id` |

### Submarket Tools

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_submarkets` | List submarkets in a metro. | `metro_id`, `sector_id` (optional) |
| `get_submarket_trends` | Historical submarket trends. | `metro_id`, `sector_id`, `submarket_id`, `frequency` |
| `get_submarket_overview` | Latest submarket snapshot. | `metro_id`, `sector_id`, `submarket_id`, `frequency` |
| `get_submarket_vintage` | Vintage data for a submarket. | `metro_id`, `sector_id`, `submarket_id` |

### Reference Data & Geo

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_sectors` | List all CRE sectors. | (none) |
| `get_categories` | List property categories. | (none) |
| `get_subcategories` | Subcategories for a category. | `category` |
| `point_in_polygon` | Find market/submarket for a lat/long. | `lat`, `long`, `area_type`, `sector_id` |

---

## Example Prompts

Once the MCP server is connected, you can ask Claude things like:

- "Search for the property at 30 Hudson Yards, New York, NY"
- "Get the sales history for property key ABC123..."
- "Find sales comps within 5 miles of downtown Chicago for office buildings sold in the last 2 years"
- "What are the market trends for the New York office sector quarterly?"
- "List all submarkets in the Boston metro area for the apartment sector"
- "Get the Commercial Location Score for this property"
- "Show me CMBS loan data for this property"
- "What are the tax assessments for this parcel?"

---

## Auth Note

The server authenticates via Basic Auth (email + API key) to get a JWT bearer token, which is cached and auto-refreshed. If you see 401 errors on data endpoints, your API key may need the CRE product subscription enabled in the [Moody's API Hub portal](https://api-hub.moodys.com). The auth token endpoint will work, but data endpoints require active CRE entitlements on the API key.

## Rate Limits

- Standard: 20 requests/second
- Premium: 30 requests/second