# CREHQ Location Intelligence [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/groundroof/crehq-mcp-server  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/crehq-location-intelligence

## Description
CREHQ chain-location tools for brands, sites, franchise data, credit signals, and whitespace.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "crehq-location-intelligence": {
    "command": "npx",
    "args": ["-y","crehq-mcp-server"]
  }
}
```

## Documentation & README

# CREHQ MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) server that turns
[CREHQ](https://crehq.com)'s **live location-intelligence REST API** into native
tools for Claude and other AI agents. Ask an agent *"where should Chipotle open
next?"*, *"which hotel chain is this venue affiliated with?"*, *"who has ever
occupied this address?"*, or *"what are Aspen Dental's credit signals?"* — and it can actually answer,
backed by CREHQ's canonical, **multi-source government-verified** database of
franchise & multi-unit brands, individual storefronts, FDD financials, credit signals, and
site-level tenancy history.

This is a thin wrapper over CREHQ's existing production API
(`https://crehq.com/wp-json/crehq/v1`). It does not store data or modify
anything server-side — it authenticates with your API key and forwards calls.

---

## What it exposes (33 tools)

**Upgrade / paywall routing**
- `crehq_request_upgrade` — use when a sandbox user asks for premium data such as credit signals, FDD/Item 19, site-selection criteria, real-estate requirements, contacts, source provenance, change history, bulk downloads, whitespace, co-tenancy, or site timeline. With a free sandbox key, this records upgrade intent in CREHQ and returns the user a clear upgrade path instead of saying the data does not exist.
- `crehq_intelligence_preview` — for Pro self-serve keys, spends the one monthly controlled intelligence preview credit and returns a bounded evidence frame without exposing raw premium tables or redistribution rights.

**Entity affiliation**
- `crehq_resolve_entity_affiliation` — resolve a venue URL, name, or address to an evidence-backed affiliation status, canonical brand, operator, and parent company across hotels, restaurants, retail, healthcare, banks, auto dealers, EV charging, and other location categories. Valid outcomes include branded, independent, not a commercial venue, and unresolved. A paid-access response preserves its exact checkout URL and CREHQ intent id. Checkout emails a new Pro key that must be installed before retrying; the current credential is not upgraded in place.

**Companies / brands**
- `crehq_companies_list` — list brands, filter by category & expansion status
- `crehq_companies_search` — resolve a brand name → CREHQ company id (start here)
- `crehq_company_get` — canonical brand profile, verified unit count, ownership
- `crehq_company_credit_signals` — credit profile, sponsor/issuer context, ratings, capital structure
- `crehq_company_franchise` — FDD fees, royalties, investment, Item 19 figures
- `crehq_company_real_estate` — site-selection criteria & target geographies
- `crehq_company_contacts` — real-estate / development decision-maker contacts

**Locations**
- `crehq_locations_list` — store records by brand / state / category
- `crehq_location_get` — one location with full attributes & verification trace
- `crehq_locations_search` — fuzzy multi-field location search
- `crehq_locations_nearby` — radius search around a lat/lng (trade-area mapping)
- `crehq_locations_bulk` — bulk pull by id list, brand list, or GeoJSON polygon
- `crehq_locations_events` — cross-brand open/close/relocate lifecycle stream
- `crehq_location_history` — full event log for one physical store

**History & flagship differentiators**
- `crehq_company_changes` — date-bounded change feed for one brand
- `crehq_company_occupancy` — point-in-time roster (footprint on a past date)
- `crehq_site_timeline` — **every brand that ever occupied an address, over time**

**Premium intelligence** (Intel & Enterprise tiers)
- `crehq_whitespace` — markets where competitors are present but the brand isn't
- `crehq_co_tenancy` — which brands cluster near this brand's stores
- `crehq_location_site_profile` — CREHQ Modeled Site Profile for one location
- `crehq_company_site_pattern` — empirical brand site pattern from observed footprint/context
- `crehq_recent_location_context` — recent observed/opening rows with traffic, demographics, and coverage flags

Modeled Site Profile outputs must be described as **CREHQ-modeled from observed
location/context data**, not as company-stated site requirements unless the
response includes explicit stated-requirement provenance.

The Modeled Site Profile REST routes are staged pending explicit production
approval. Until those routes are published, these three tools may return a
`404` even though the MCP catalog advertises them for local testing.

**Datasets**
- `crehq_datasets_list` / `crehq_dataset_get` / `crehq_dataset_download` / `crehq_dataset_categories`
- `crehq_purchased_datasets_list` — list dataset snapshots purchased by the connected key owner, including snapshot date and hosted MCP access status.
- `crehq_purchased_dataset_locations` — query rows from a buyer-owned point-in-time dataset snapshot during the hosted access window.

**Trends**
- `crehq_trends_company` — outlet/fee/financial time series for a brand
- `crehq_trends_geographic` — metro/state concentration & velocity

---

## Getting an API key

1. **Free sandbox** (1,000 calls/mo, 2 req/s, no credit card):
   https://crehq.com/developers/sandbox/ — enter your email, complete the
   browser verification challenge, and a key is emailed to you.
   The key is delivered by email only and looks like `crehq_live_xxxxxxxx…`.
   Sandbox keys can run bounded location lookups (`crehq_locations_list` by
   brand, and `crehq_locations_nearby` by radius) and call the entity-affiliation
   resolver once per month. If the user asks for premium
   intelligence, call `crehq_request_upgrade`; it records the requested topic
   for CREHQ follow-up and tells the user what to upgrade.
2. **Pro MCP** — **$99/mo**, self-serve Stripe checkout. Includes bounded D1
   location queries, selected D2 provenance fields, 25,000 core calls/month, up
   to 250 affiliation resolver calls/month, and one controlled intelligence
   preview per month. Start at
   https://crehq.com/developers/sandbox/#pro-checkout.
3. **Datasets / Intelligence / Enterprise** — buy licensed point-in-time
   dataset snapshots when you need the file; use enterprise licensing for
   premium intelligence, refresh plans, API/feed delivery, redistribution,
   embedded rights, and SLAs. See https://crehq.com/pricing/.

---

## Fastest way to try CREHQ in an agent

1. Get a sandbox key at https://crehq.com/developers/sandbox/.
2. For hosted/remote MCP clients, add `https://mcp.crehq.com/mcp` and authorize
   with that key.
3. For local stdio clients, install with `npx -y crehq-mcp-server` and set
   `CREHQ_API_KEY`.
4. Ask: `Use CREHQ to identify the brand, operator, and parent affiliation of
   the venue at https://www.earleycrescent.org/.`

Self-serve keys expose the affiliation resolver, bounded location lookups,
upgrade routing, purchased-dataset access, and the controlled intelligence
preview. The backend still enforces the key's actual Free, Pro, and purchased
dataset entitlements, returning a structured upgrade or purchase response when
needed. Intel and Enterprise keys expose broader API tools according to the
key's CREHQ tier.

---

## Install & build

Requires Node.js ≥ 18.

Install the published stdio server with `npx`:

```bash
CREHQ_API_KEY=crehq_live_xxxxx npx crehq-mcp-server
```

Or build from source:

```bash
git clone <this-repo> crehq-mcp-server
cd crehq-mcp-server
npm install
npm run build          # compiles TypeScript → dist/
cp .env.example .env    # then edit .env and set CREHQ_API_KEY
```

Verify your key against the live API before wiring up a client:

```bash
export CREHQ_API_KEY=crehq_live_xxxxx
./test.sh               # exercises 6 read endpoints with curl
```

Run the server standalone (it speaks MCP over stdio, so it will wait for a
client on stdin — Ctrl-C to exit):

```bash
CREHQ_API_KEY=crehq_live_xxxxx node dist/index.js
```

---

## Connect to Claude Desktop

Add this to your `claude_desktop_config.json`:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "crehq": {
      "command": "npx",
      "args": ["-y", "crehq-mcp-server"],
      "env": {
        "CREHQ_API_KEY": "crehq_live_your_key_here"
      }
    }
  }
}
```

Restart Claude Desktop. The CREHQ tools appear under the tools (🔌) menu.

### Other MCP clients

Any stdio-capable MCP client (Claude Code, Cursor, Cline, Continue, the
`mcp` CLI, custom `@modelcontextprotocol/sdk` clients, etc.) connects the same
way — run `node dist/index.js` as the server command with `CREHQ_API_KEY` in
the environment.

**Claude Code:**
```bash
claude mcp add crehq --env CREHQ_API_KEY=crehq_live_xxxxx -- npx crehq-mcp-server
```

## Hosted remote connector

The hosted Cloudflare Worker version is kept in `remote/`. It provides the
same CREHQ connector as a remote MCP server at `https://mcp.crehq.com/mcp`, with
OAuth/key exchange and scope gating for premium tools. Its own deploy notes are
in `remote/DEPLOY.md` and connector-submission copy is in
`remote/CONNECTOR-SUBMISSION.md`.

The MCP Registry metadata lives in `server.json`, with registry ownership
declared by `mcpName` in `package.json`.

## Maintainer workflow

GitHub Actions owns the repeatable release path:

- `CI` builds and tests the stdio package and the hosted Worker on every push.
- `Deploy Remote MCP` deploys `remote/` changes to Cloudflare Workers and then
  verifies `https://mcp.crehq.com/health`.
- `Publish npm` publishes the stdio package from a `vX.Y.Z` tag or manual
  workflow dispatch. It skips safely when that package version already exists.

Required repository secrets are already named:

- `NPM_TOKEN`
- `CLOUDFLARE_API_TOKEN`
- `CLOUDFLARE_ACCOUNT_ID`

---

## Configuration

| Env var            | Required | Default                                      | Purpose                              |
|--------------------|----------|----------------------------------------------|--------------------------------------|
| `CREHQ_API_KEY`    | yes      | —                                            | Your `crehq_live_…` key              |
| `CREHQ_API_BASE`   | no       | `https://crehq.com/wp-json/crehq/v1`         | Override API base (staging/proxy)    |
| `CREHQ_TIMEOUT_MS` | no       | `30000`                                      | Per-request timeout in ms            |
| `CREHQ_API_SURFACE` | no      | `auto`                                       | Auto-detect sandbox vs full key; can be `selfserve` or `full` for debugging |

---

## Error handling

Tools never crash the agent's turn — failures come back as a readable message
with a fix-it hint:

- **No key set** → instructs you to set `CREHQ_API_KEY` and links the sandbox.
- **401 / 403** → "invalid or revoked key / endpoint not in your tier" + upgrade link. For credit signals, FDD, site-selection criteria, contacts, provenance, change history, bulk data, whitespace, co-tenancy, or site timeline, call `crehq_request_upgrade`.
- **404** → "check the id/slug; resolve it with a search tool first."
- **429** → respects `Retry-After`; reminds you of the free-tier 2 req/s limit.
- **5xx / timeout / network** → transient-error guidance to retry with backoff.

Pagination, cache, and stream cursors (`X-WP-Total`, `X-CREHQ-Next-Since`,
`X-CREHQ-Cache`, rate-limit headers) are surfaced in a `response metadata`
footer on each result so the agent can paginate and poll correctly.

---

## Note on testing

The build, typecheck, MCP protocol handshake, tool catalog, argument
validation, and the full HTTP request/response/error pipeline are verified
end-to-end against the **live** production API (a real request returns a real
`403 Invalid or revoked API key` with the correct hint). Fetching real data
rows requires a valid key — the sandbox key is delivered by email, so set
`CREHQ_API_KEY` and run `./test.sh` to confirm live data responses.

---

## License

MIT. CREHQ data is licensed separately per your API tier/contract.