Homedata MCP server (Node)

UK property data as tools for AI assistants. Ask Claude, Cursor, Codex or any Model Context Protocol client about an address and it can look up the property record, EPC, council tax, flood and other environmental risks, planning, schools, broadband, crime, local amenities and area price trends through the Homedata API.

The tools are exactly the self-serve endpoints of the Homedata Developer Playground: the same names, the same arguments and the same prices.

Install

Requires Node 18 or newer.

npm install -g homedata-mcp

or run it without installing:

npx -y homedata-mcp

There is an equivalent Python package with the same tools, generated from the same list.

Get an API key

Create an account at homedata.co.uk/register, verify your email, and copy your key from the developer dashboard. Calls are paid for in tokens from a prepaid balance; see homedata.co.uk/pricing. Every tool's description states what it costs, and every call reports what it actually cost (see What a call costs).

Without a key the server still starts, with two helpers, start_homedata_signup and check_homedata_api_key, so your assistant can walk you through getting one. Neither helper calls the API.

Connect it to your assistant

Most clients take the same command, arguments and environment. For Claude Desktop, add this to claude_desktop_config.json and restart the app:

{
  "mcpServers": {
    "homedata": {
      "command": "npx",
      "args": ["-y", "homedata-mcp"],
      "env": { "HOMEDATA_API_KEY": "your_key" }
    }
  }
}

With npm install -g homedata-mcp, use "command": "homedata-mcp" and no args.

Claude Code:

claude mcp add homedata --env HOMEDATA_API_KEY=your_key -- npx -y homedata-mcp

Step-by-step guides for Claude Desktop, Claude Code, Cursor, Codex CLI, Windsurf, Cline, Continue.dev and Zed are at homedata.co.uk/mcp.

Using the tools

Call address_match with a street address and postcode to get a UPRN, then use the property tools with that UPRN. For a whole property, one tier call is cheaper than many small ones: property_base, then property_core (the usual full picture), then property_complete. property_discovery costs 1 token and shows what a property has before you commit to a tier.

Both address and postcode are required for matching. Success costs 5 tokens and returns the address-level record plus address_resolution. HTTP 422 with reason no_match or multiple_matches is never charged; clarify the address instead of guessing a UPRN.

Tool	Tokens	What it returns
address_match	5	Match a submitted UK street address and postcode to a UPRN. A 200 response returns the address-level retrieve body plus address_resolution.
address_postcode	2	List every registered address at a UK postcode, with the UPRN for each one.
amenities_all	5	Every amenity group near a property in one response: food, education, healthcare, financial, civic, worship, culture, convenience, green spaces, transport and shops.
amenities_civic	1	Civic places near a property: post offices, town halls, courthouses, fire and police stations, community centres.
amenities_convenience	1	Everyday conveniences near a property: public toilets, charging points, parcel lockers and similar.
amenities_culture	1	Culture and leisure near a property: theatres, cinemas, music venues, museums, galleries and attractions.
amenities_education	1	Education near a property: schools, nurseries, colleges, universities, childcare and libraries. For Ofsted ratings and pupil numbers use schools.
amenities_financial	1	Banks, cash machines and money services near a property.
amenities_food	1	Places to eat and drink near a property: cafes, restaurants, pubs, bars, takeaways.
amenities_green_spaces	1	Green space near a property: parks, playgrounds, gardens, nature reserves, commons and sports pitches.
amenities_healthcare	1	Health services near a property as mapped locally: doctors, dentists, clinics, hospitals, pharmacies and care homes. For regulator-registered records use healthcare_all and its per-type tools.
amenities_shops	1	Shops near a property, from supermarkets to specialist retailers.
amenities_transport	1	Transport stops near a property: bus stops, railway stations, tram stops and ferry terminals.
amenities_worship

What a call costs

Each tool's description states its price in tokens. When the API reports what a call actually cost, the tool result carries it in its metadata:

{ "homedata": { "tokens_charged": "25", "tokens_balance": "9975" } }

Arguments are checked before anything is sent: a call with a missing, malformed or unknown argument is refused by the server and never reaches the API.

Command line

The package also installs homedata, built from the same tool list:

homedata tools                                   # every tool and its price
homedata address_match --address "10 Downing Street" --postcode "SW1A 2AA"
homedata property_core --uprn 100023336956 --field epc
homedata calc_mortgage --price 300000 --deposit 30000 --rate 4.5 --term 25
homedata risks --help                            # the arguments for one tool

--field <dotted.path> prints one value, --compact prints one line of JSON, and the tokens a call cost are printed to stderr. The calculators are free and need no key.

Configuration

Variable	Required	Default
HOMEDATA_API_KEY	for everything except the calculators and the signup helpers	none
HOMEDATA_BASE_URL	no	https://api.homedata.co.uk

How the tool list is kept right

src/manifest/ is a vendored copy of the tool list from the Python package, which generates it from the Developer Playground catalogue. src/manifest/SOURCE.json records the exact commit and a hash per file, and CI fails if a vendored byte differs from that commit. Every tool here is built from that copy, and the same guard that checks the Python server checks this one, so the two cannot describe the API differently. See CONTRIBUTING.md.

Development

git clone https://github.com/wehomemove/homedata-mcp-node.git
cd homedata-mcp-node
npm ci
npm run build
npm test

Licence

MIT. See LICENSE.

The Home widget's icons are Phosphor Icons, MIT licence, Copyright (c) 2023 Phosphor Icons. They are copied unchanged from the @phosphor-icons/core package at build time by scripts/home-icons.mjs.