UK housing data for AI assistants. An open source MCP server that provides structured access to Energy Performance Certificates, social housing stock, house prices, rental statistics, and more — all from official government sources.
10 tools across 3 official UK government data sources
Everything you need to connect, query, and integrate OpenHousing.AI
You need Python 3.11+ and uv package manager installed. For EPC tools, register for a free API key at EPC Open Data. RSH and ONS tools require no authentication.
git clone https://github.com/yantraworks/openhousing-ai.git cd openhousing-ai cp .env.example .env # Add your EPC API credentials to .env uv sync uv run openhousing
docker build -t openhousing-ai . docker run -i --rm --env-file .env openhousing-ai
For remote MCP clients, run in HTTP transport mode:
uv run openhousing --transport http --port 8080
Search for Energy Performance Certificates in England and Wales. Accepts postcodes in any format, fuzzy local authority name matching.
| Parameter | Type | Description | |
|---|---|---|---|
| postcode | string | optional | UK postcode (e.g. "SW1A 1AA") |
| address | string | optional | Street address or partial match |
| local_authority | string | optional | Local authority name or ONS code |
| energy_band | string | optional | EPC rating band (A–G) |
| property_type | string | optional | house, flat, bungalow, maisonette |
| from_date | string | optional | Lodgement date from (YYYY-MM-DD) |
| to_date | string | optional | Lodgement date to (YYYY-MM-DD) |
| max_results | integer | optional | Results to return (default 25, max 5000) |
Retrieve full EPC history for a specific property by its Unique Property Reference Number.
| Parameter | Type | Description | |
|---|---|---|---|
| uprn | string | required | UPRN (up to 12 digits) |
Aggregated EPC statistics for a local authority. Computes band distribution, property type breakdown, average efficiency scores, and MEES compliance metrics.
| Parameter | Type | Description | |
|---|---|---|---|
| local_authority | string | required | Local authority name or code |
| tenure | string | optional | social, private-rented, owner-occupied |
| group_by | string | optional | energy_band, property_type, construction_age |
Search social housing stock data from the RSH Statistical Data Return.
| Parameter | Type | Description | |
|---|---|---|---|
| provider_name | string | optional | Registered provider name (partial match) |
| local_authority | string | optional | Local authority name or code |
| year | integer | optional | Reporting year (default latest) |
Comprehensive profile of a registered social housing provider including stock breakdown, rents, vacancies, RTB sales, and geographic spread.
| Parameter | Type | Description | |
|---|---|---|---|
| provider_name | string | required | Provider name (fuzzy match) |
Compare key metrics across 2–5 registered providers side by side.
| Parameter | Type | Description | |
|---|---|---|---|
| providers | list[string] | required | List of 2–5 provider names |
| metrics | list[string] | optional | stock, rents, vacancies, rtb_sales |
| Parameter | Type | Description | |
|---|---|---|---|
| location | string | required | Local authority, region, or country |
| from_date | string | optional | Start date (YYYY-MM) |
| to_date | string | optional | End date (YYYY-MM) |
| property_type | string | optional | detached, semi-detached, terraced, flat |
| Parameter | Type | Description | |
|---|---|---|---|
| location | string | required | Local authority, region, or country |
| bedrooms | integer | optional | Number of bedrooms (1–4+) |
| Parameter | Type | Description | |
|---|---|---|---|
| location | string | required | Local authority name |
| measure | string | optional | median or lower_quartile (default median) |
| Parameter | Type | Description | |
|---|---|---|---|
| location | string | required | Local authority, region, or country |
| tenure | string | optional | market, affordable_rent, social_rent, shared_ownership |
Add to your claude_desktop_config.json:
{
"mcpServers": {
"openhousing": {
"command": "uv",
"args": ["run", "--directory", "/path/to/openhousing-ai", "openhousing"],
"env": {
"EPC_API_EMAIL": "your-email",
"EPC_API_KEY": "your-key"
}
}
}
}
Add to .mcp.json in your project root:
{
"mcpServers": {
"openhousing": {
"command": "uv",
"args": ["run", "--directory", "/path/to/openhousing-ai", "openhousing"],
"env": {
"EPC_API_EMAIL": "your-email",
"EPC_API_KEY": "your-key"
}
}
}
}
Connect to the hosted instance via Streamable HTTP:
MCP Endpoint: https://openhousing-ai-447203134530.us-west1.run.app/mcp/ SSE Endpoint: https://openhousing-ai-447203134530.us-west1.run.app/sse/
| Variable | Required | Default | Description |
|---|---|---|---|
| EPC_API_EMAIL | EPC tools | — | Email registered with EPC Open Data |
| EPC_API_KEY | EPC tools | — | API key from EPC Open Data |
| OPENHOUSING_CACHE_TTL | no | 3600 | Cache TTL in seconds |
| OPENHOUSING_LOG_LEVEL | no | INFO | Logging level |
| OPENHOUSING_RATE_LIMIT | no | 10 | Max requests/sec to upstream APIs |
| OPENHOUSING_PORT | no | 8080 | HTTP transport port |
| EPC | Energy Performance Certificate — rates building energy efficiency A (best) to G (worst). Required for sale/rental. |
| RSH | Regulator of Social Housing — government body regulating social housing providers in England. |
| CORE | Continuous Recording of Lettings and Sales — national data collection for social housing lettings. |
| PRP | Private Registered Provider — housing association registered with the RSH. |
| UPRN | Unique Property Reference Number — unique identifier for every addressable location in GB. |
| MEES | Minimum Energy Efficiency Standards — currently EPC E for rentals, proposed EPC C by 2030. |
| RTB | Right to Buy — policy allowing eligible social tenants to purchase their home at a discount. |
| Social Rent | Rent calculated using government formula based on local earnings and property values. Lower than affordable rent. |
| Affordable Rent | Rent set at up to 80% of local market rent, including service charges. |
| LCHO | Low Cost Home Ownership — includes shared ownership, rent to buy, and intermediate tenure. |
| SDR | Statistical Data Return — annual data collection from registered providers by the RSH. |
| UKHPI | UK House Price Index — monthly index from ONS measuring house price changes. |
| LHA | Local Housing Allowance — rate for Housing Benefit/UC housing element for private renters. |
| Awaab's Law | Social Housing (Regulation) Act 2023 provisions requiring landlords to fix hazards within set timeframes. |
| DHS | Decent Homes Standard — minimum standard covering fitness, repair, facilities, and thermal comfort. |
| S106 | Section 106 agreements — legal agreements requiring affordable housing in new developments. |
| HMO | House in Multiple Occupation — property rented by 3+ people not from one household. |
| ONS | Office for National Statistics — UK national statistical institute. |
All data from official UK government APIs under the Open Government Licence v3.0
Energy Performance Certificates for domestic buildings in England and Wales. Ratings, property details, insulation, heating, CO2 emissions, improvement recommendations.
epc.opendatacommunities.orgSocial housing stock from private registered providers. Stock by area, property type, bedroom count, tenure, rents, lettings, Right to Buy sales, vacancies.
gov.uk/rshHouse price indices, private rental market statistics, housing affordability ratios, new build starts and completions. Monthly, quarterly, and annual data.
ons.gov.uk/housing