Homedata MCP Server

A Model Context Protocol server that exposes the Homedata UK property data API as native tools for AI coding assistants - Claude Desktop, Claude Code, Cursor, and any other MCP client.

29M UK addresses keyed by UPRN, with EPCs, sale history, planning, flood risk, council tax, demographics, crime, schools, broadband and transport - all queryable directly from your assistant chat.

Data is sourced from Home.co.uk's 30-year panel of partners, the Environment Agency, ONS Census 2021, the Valuation Office Agency, Ofcom, Ofsted, data.police.uk and HM Land Registry.

Install

Requires Python 3.10+.

pip install homedata-mcp

For local development from this repository:

git clone https://github.com/wehomemove/homedata-mcp.git
cd homedata-mcp
pip install -e .

You will need a Homedata API key. Sign up at homedata.co.uk/developer - the Free tier gives 100 calls / month with no card required.

export HOMEDATA_API_KEY=hd_live_xxx
homedata-mcp --help

CLI

The package also installs a homedata command — same data as the MCP server but for human shells, scripting, and CI. Useful for quick lookups, demos, and piping into other tools.

homedata property 100021421083
homedata epc 100021421083 --field current_energy_efficiency
homedata search "10 downing street" --postcode SW1A2AA
homedata flood 100021421083 --compact
homedata batch 100021421083 100022121211

Pass --field <dotted.path> to extract a single value (handy for shell pipelines) and --compact for single-line JSON. Reads the same HOMEDATA_API_KEY env var as the MCP server. Run homedata --help for the full list of subcommands.

Wire it into Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "homedata": {
      "command": "homedata-mcp",
      "env": {
        "HOMEDATA_API_KEY": "your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop. You should see the 16 Homedata tools appear in the tool picker.

Cursor / Claude Code

Both Cursor and Claude Code accept the same MCP server spec. Add an entry pointing command at homedata-mcp and put your key in env.

Tools

All UPRN tools take a single 12-digit Unique Property Reference Number; all postcode tools accept any common UK postcode format.

Typical workflow

1. Resolve text → UPRN with search_address.

2. Look up the property: lookup_property, lookup_epc, lookup_council_tax, lookup_flood_risk.

3. Add market context: search_property_listings, get_property_sales, get_comparables.

4. Add area context: get_postcode_profile (cheap one-shot), or call get_demographics / get_crime / get_schools / get_broadband / get_transport individually.

Configuration

Every tool returns either the parsed JSON body from the API, or {"error": "...", "status_code": N, "detail": ...} on failure - tools never raise exceptions out into the MCP protocol layer.

Pricing

Calls made via this MCP server count against your Homedata API plan exactly the same as any other API call. Plans (as of writing):

See homedata.co.uk/pricing for the current list.

Development

pip install -e ".[dev]"
HOMEDATA_API_KEY=hd_live_xxx pytest -v

Tests are skipped automatically when no API key is present, so the suite is safe to run in CI without secrets.

Project layout

homedata-mcp/
  pyproject.toml
  README.md
  homedata_mcp/
    __init__.py
    server.py           # FastMCP server + CLI entry point
    client.py           # httpx wrapper with auth + uniform error handling
    tools/
      __init__.py
      property.py       # lookup_property, batch_property_lookup
      epc.py            # lookup_epc
      risk.py           # lookup_flood_risk, lookup_council_tax
      listings.py       # search_property_listings, get_property_sales, get_comparables
      planning.py       # get_planning_applications
      local.py          # get_demographics, get_crime, get_schools, get_broadband, get_transport
      address.py        # search_address
      profile.py        # get_postcode_profile
  tests/
    test_tools.py

License

MIT - see LICENSE.