Homedata MCP server

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 Python 3.10 or newer.

pip install homedata-mcp

or run it without installing, with uv:

uvx homedata-mcp

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": "uvx",
      "args": ["homedata-mcp"],
      "env": { "HOMEDATA_API_KEY": "your_key" }
    }
  }
}

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

Claude Code:

claude mcp add homedata --env HOMEDATA_API_KEY=your_key -- uvx 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

Start with address_match to match an address and postcode to 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.

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

--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

How the tool list is kept right

homedata_mcp/manifest/tools.json is generated from the Developer Playground catalogue by scripts/generate-manifest.mjs, and every tool is built from it. The test suite fails if the server's tools, arguments, requests or stated prices differ from the manifest, and a weekly check fails if the Playground's public catalogue has moved on since the manifest was generated. See CONTRIBUTING.md.

Development

git clone https://github.com/wehomemove/homedata-mcp.git
cd homedata-mcp
python -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
pytest

Licence

MIT. See LICENSE.