{
  "markdown": "# CREHQ MCP Server\n\nA [Model Context Protocol](https://modelcontextprotocol.io) server that turns\n[CREHQ](https://crehq.com)'s **live location-intelligence REST API** into native\ntools for Claude and other AI agents. Ask an agent *\"where should Chipotle open\nnext?\"*, *\"which hotel chain is this venue affiliated with?\"*, *\"who has ever\noccupied this address?\"*, or *\"what are Aspen Dental's credit signals?\"* — and it can actually answer,\nbacked by CREHQ's canonical, **multi-source government-verified** database of\nfranchise & multi-unit brands, individual storefronts, FDD financials, credit signals, and\nsite-level tenancy history.\n\nThis is a thin wrapper over CREHQ's existing production API\n(`https://crehq.com/wp-json/crehq/v1`). It does not store data or modify\nanything server-side — it authenticates with your API key and forwards calls.\n\n---\n\n## What it exposes (33 tools)\n\n**Upgrade / paywall routing**\n- `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.\n- `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.\n\n**Entity affiliation**\n- `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.\n\n**Companies / brands**\n- `crehq_companies_list` — list brands, filter by category & expansion status\n- `crehq_companies_search` — resolve a brand name → CREHQ company id (start here)\n- `crehq_company_get` — canonical brand profile, verified unit count, ownership\n- `crehq_company_credit_signals` — credit profile, sponsor/issuer context, ratings, capital structure\n- `crehq_company_franchise` — FDD fees, royalties, investment, Item 19 figures\n- `crehq_company_real_estate` — site-selection criteria & target geographies\n- `crehq_company_contacts` — real-estate / development decision-maker contacts\n\n**Locations**\n- `crehq_locations_list` — store records by brand / state / category\n- `crehq_location_get` — one location with full attributes & verification trace\n- `crehq_locations_search` — fuzzy multi-field location search\n- `crehq_locations_nearby` — radius search around a lat/lng (trade-area mapping)\n- `crehq_locations_bulk` — bulk pull by id list, brand list, or GeoJSON polygon\n- `crehq_locations_events` — cross-brand open/close/relocate lifecycle stream\n- `crehq_location_history` — full event log for one physical store\n\n**History & flagship differentiators**\n- `crehq_company_changes` — date-bounded change feed for one brand\n- `crehq_company_occupancy` — point-in-time roster (footprint on a past date)\n- `crehq_site_timeline` — **every brand that ever occupied an address, over time**\n\n**Premium intelligence** (Intel & Enterprise tiers)\n- `crehq_whitespace` — markets where competitors are present but the brand isn't\n- `crehq_co_tenancy` — which brands cluster near this brand's stores\n- `crehq_location_site_profile` — CREHQ Modeled Site Profile for one location\n- `crehq_company_site_pattern` — empirical brand site pattern from observed footprint/context\n- `crehq_recent_location_context` — recent observed/opening rows with traffic, demographics, and coverage flags\n\nModeled Site Profile outputs must be described as **CREHQ-modeled from observed\nlocation/context data**, not as company-stated site requirements unless the\nresponse includes explicit stated-requirement provenance.\n\nThe Modeled Site Profile REST routes are staged pending explicit production\napproval. Until those routes are published, these three tools may return a\n`404` even though the MCP catalog advertises them for local testing.\n\n**Datasets**\n- `crehq_datasets_list` / `crehq_dataset_get` / `crehq_dataset_download` / `crehq_dataset_categories`\n- `crehq_purchased_datasets_list` — list dataset snapshots purchased by the connected key owner, including snapshot date and hosted MCP access status.\n- `crehq_purchased_dataset_locations` — query rows from a buyer-owned point-in-time dataset snapshot during the hosted access window.\n\n**Trends**\n- `crehq_trends_company` — outlet/fee/financial time series for a brand\n- `crehq_trends_geographic` — metro/state concentration & velocity\n\n---\n\n## Getting an API key\n\n1. **Free sandbox** (1,000 calls/mo, 2 req/s, no credit card):\n   https://crehq.com/developers/sandbox/ — enter your email, complete the\n   browser verification challenge, and a key is emailed to you.\n   The key is delivered by email only and looks like `crehq_live_xxxxxxxx…`.\n   Sandbox keys can run bounded location lookups (`crehq_locations_list` by\n   brand, and `crehq_locations_nearby` by radius) and call the entity-affiliation\n   resolver once per month. If the user asks for premium\n   intelligence, call `crehq_request_upgrade`; it records the requested topic\n   for CREHQ follow-up and tells the user what to upgrade.\n2. **Pro MCP** — **$99/mo**, self-serve Stripe checkout. Includes bounded D1\n   location queries, selected D2 provenance fields, 25,000 core calls/month, up\n   to 250 affiliation resolver calls/month, and one controlled intelligence\n   preview per month. Start at\n   https://crehq.com/developers/sandbox/#pro-checkout.\n3. **Datasets / Intelligence / Enterprise** — buy licensed point-in-time\n   dataset snapshots when you need the file; use enterprise licensing for\n   premium intelligence, refresh plans, API/feed delivery, redistribution,\n   embedded rights, and SLAs. See https://crehq.com/pricing/.\n\n---\n\n## Fastest way to try CREHQ in an agent\n\n1. Get a sandbox key at https://crehq.com/developers/sandbox/.\n2. For hosted/remote MCP clients, add `https://mcp.crehq.com/mcp` and authorize\n   with that key.\n3. For local stdio clients, install with `npx -y crehq-mcp-server` and set\n   `CREHQ_API_KEY`.\n4. Ask: `Use CREHQ to identify the brand, operator, and parent affiliation of\n   the venue at https://www.earleycrescent.org/.`\n\nSelf-serve keys expose the affiliation resolver, bounded location lookups,\nupgrade routing, purchased-dataset access, and the controlled intelligence\npreview. The backend still enforces the key's actual Free, Pro, and purchased\ndataset entitlements, returning a structured upgrade or purchase response when\nneeded. Intel and Enterprise keys expose broader API tools according to the\nkey's CREHQ tier.\n\n---\n\n## Install & build\n\nRequires Node.js ≥ 18.\n\nInstall the published stdio server with `npx`:\n\n```bash\nCREHQ_API_KEY=crehq_live_xxxxx npx crehq-mcp-server\n```\n\nOr build from source:\n\n```bash\ngit clone <this-repo> crehq-mcp-server\ncd crehq-mcp-server\nnpm install\nnpm run build          # compiles TypeScript → dist/\ncp .env.example .env    # then edit .env and set CREHQ_API_KEY\n```\n\nVerify your key against the live API before wiring up a client:\n\n```bash\nexport CREHQ_API_KEY=crehq_live_xxxxx\n./test.sh               # exercises 6 read endpoints with curl\n```\n\nRun the server standalone (it speaks MCP over stdio, so it will wait for a\nclient on stdin — Ctrl-C to exit):\n\n```bash\nCREHQ_API_KEY=crehq_live_xxxxx node dist/index.js\n```\n\n---\n\n## Connect to Claude Desktop\n\nAdd this to your `claude_desktop_config.json`:\n\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"crehq\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"crehq-mcp-server\"],\n      \"env\": {\n        \"CREHQ_API_KEY\": \"crehq_live_your_key_here\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. The CREHQ tools appear under the tools (🔌) menu.\n\n### Other MCP clients\n\nAny stdio-capable MCP client (Claude Code, Cursor, Cline, Continue, the\n`mcp` CLI, custom `@modelcontextprotocol/sdk` clients, etc.) connects the same\nway — run `node dist/index.js` as the server command with `CREHQ_API_KEY` in\nthe environment.\n\n**Claude Code:**\n```bash\nclaude mcp add crehq --env CREHQ_API_KEY=crehq_live_xxxxx -- npx crehq-mcp-server\n```\n\n## Hosted remote connector\n\nThe hosted Cloudflare Worker version is kept in `remote/`. It provides the\nsame CREHQ connector as a remote MCP server at `https://mcp.crehq.com/mcp`, with\nOAuth/key exchange and scope gating for premium tools. Its own deploy notes are\nin `remote/DEPLOY.md` and connector-submission copy is in\n`remote/CONNECTOR-SUBMISSION.md`.\n\nThe MCP Registry metadata lives in `server.json`, with registry ownership\ndeclared by `mcpName` in `package.json`.\n\n## Maintainer workflow\n\nGitHub Actions owns the repeatable release path:\n\n- `CI` builds and tests the stdio package and the hosted Worker on every push.\n- `Deploy Remote MCP` deploys `remote/` changes to Cloudflare Workers and then\n  verifies `https://mcp.crehq.com/health`.\n- `Publish npm` publishes the stdio package from a `vX.Y.Z` tag or manual\n  workflow dispatch. It skips safely when that package version already exists.\n\nRequired repository secrets are already named:\n\n- `NPM_TOKEN`\n- `CLOUDFLARE_API_TOKEN`\n- `CLOUDFLARE_ACCOUNT_ID`\n\n---\n\n## Configuration\n\n| Env var            | Required | Default                                      | Purpose                              |\n|--------------------|----------|----------------------------------------------|--------------------------------------|\n| `CREHQ_API_KEY`    | yes      | —                                            | Your `crehq_live_…` key              |\n| `CREHQ_API_BASE`   | no       | `https://crehq.com/wp-json/crehq/v1`         | Override API base (staging/proxy)    |\n| `CREHQ_TIMEOUT_MS` | no       | `30000`                                      | Per-request timeout in ms            |\n| `CREHQ_API_SURFACE` | no      | `auto`                                       | Auto-detect sandbox vs full key; can be `selfserve` or `full` for debugging |\n\n---\n\n## Error handling\n\nTools never crash the agent's turn — failures come back as a readable message\nwith a fix-it hint:\n\n- **No key set** → instructs you to set `CREHQ_API_KEY` and links the sandbox.\n- **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`.\n- **404** → \"check the id/slug; resolve it with a search tool first.\"\n- **429** → respects `Retry-After`; reminds you of the free-tier 2 req/s limit.\n- **5xx / timeout / network** → transient-error guidance to retry with backoff.\n\nPagination, cache, and stream cursors (`X-WP-Total`, `X-CREHQ-Next-Since`,\n`X-CREHQ-Cache`, rate-limit headers) are surfaced in a `response metadata`\nfooter on each result so the agent can paginate and poll correctly.\n\n---\n\n## Note on testing\n\nThe build, typecheck, MCP protocol handshake, tool catalog, argument\nvalidation, and the full HTTP request/response/error pipeline are verified\nend-to-end against the **live** production API (a real request returns a real\n`403 Invalid or revoked API key` with the correct hint). Fetching real data\nrows requires a valid key — the sandbox key is delivered by email, so set\n`CREHQ_API_KEY` and run `./test.sh` to confirm live data responses.\n\n---\n\n## License\n\nMIT. CREHQ data is licensed separately per your API tier/contract.\n",
  "bytes": 11973,
  "sha": "18f5a52e1f6ae1d0cd687f283cf0917e995b6a9cec57b7fbd7e82d950fbcbcb9",
  "repo_slug": "groundroof/crehq-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_groundroof_crehq_mcp_server_43b8d146/readme"
}