MCP Server: io.github.paulieb89/property-shared

The MCP server io.github.paulieb89/property-shared provides a UK property data bundle aggregating multiple sources. It pulls Land Registry sales data, EPC certificates, Rightmove listings, rental yields, stamp duty calculations, and planning portal links, and it also includes Companies House records.

🛠️ Key Features

Aggregates UK property datasets and related calculations/records
Sources include Land Registry, EPC, Rightmove, and Companies House
Includes rental yield data and stamp duty calculations

🚀 Use Cases

Retrieve UK property listings and supporting records in one place
Compare or analyze EPC and Land Registry sales alongside Rightmove data
Use stamp duty and rental yields for property-related planning

⚡ Developer Benefits

Exposes data via an MCP server interface (toolCount: 13)
Also designed for use as a Python library, CLI, and HTTP API

⚠️ Limitations

Description provided does not specify schemas, query methods, or coverage details for each data source

Property Shared

UK property data in one package. Pulls Land Registry sales, EPC certificates, Rightmove listings, rental yields, stamp duty calculations, planning portal links, and Companies House records.

Use it as a Python library, CLI, HTTP API, or MCP server.

What You Get

Data Source	What It Returns
Land Registry PPD	Sold prices, dates, property types, area comps with median/percentiles
EPC (GOV.UK)	Energy ratings, floor area, heating costs. England & Wales only. Certificate lookup and summary search — see EPC notes below
Rightmove	Current listings (sale + rent), prices, agents, listing details
Yield Analysis	Gross yield from PPD sales + Rightmove rentals combined
Stamp Duty	SDLT calculation with April 2025 bands, BTL surcharge, FTB relief
Block Analyzer	Groups flat sales by building to spot investor exits
Planning	Local council planning portal lookup (99 verified councils, stdio only)
Companies House	Company search and lookup by name or number

Skills & Plugins

Property and Legal packs coming soon. Please get in contact if you have working experiance or expert knowledge in UK property investing, UK Estate Agents, Property and Conveyencing and would like to help shape this. paul@bouch.dev

Use as MCP Server

No install required — paste the URL into your MCP client config and go.

Claude Code, Cursor, any MCP client:

json

{
  "mcpServers": {
    "property-shared": {
      "type": "http",
      "url": "https://property-shared.fly.dev/mcp"
    }
  }
}

Install

bash

pip install property-shared

# or with uv
uv add property-shared

Extras: [cli] for CLI, [api] for HTTP server.

bash

pip install property-shared[cli]
# or
uv add property-shared --extra cli

Use as a Python Library

python

from property_core import PPDService, calculate_yield, calculate_stamp_duty

# Get comparable sales for a postcode
comps = PPDService().comps("SW1A 1AA", months=24, property_type="F")
print(f"Median flat price: {comps.median:,}")

# Calculate rental yield
import asyncio
result = asyncio.run(calculate_yield("NG1 1AA", property_type="F"))
print(f"Gross yield: {result.gross_yield_pct}%")

# Stamp duty
sdlt = calculate_stamp_duty(250000, additional_property=True)
print(f"SDLT: {sdlt.total_sdlt:,.0f} ({sdlt.effective_rate}%)")

All models are available at top level:

python

from property_core import (
    PPDTransaction, PPDCompsResponse, EPCData,
    RightmoveListing, RightmoveListingDetail,
    PropertyReport, YieldAnalysis, RentalAnalysis,
    BlockAnalysisResponse, CompanyRecord, StampDutyResult,
)

Interpretation helpers (core returns numbers, you decide how to label them):

python

from property_core import classify_yield, classify_data_quality, generate_insights

Use as CLI

bash

pip install property-shared[cli]  # or: uv add property-shared --extra cli

# Comparable sales
property-cli ppd comps "SW1A 1AA" --months 24 --property-type F

# Rental yield
property-cli analysis yield "NG1 1AA" --property-type F

# Stamp duty
property-cli calc stamp-duty 300000

# Rightmove search (with sort)
property-cli rightmove search-url "NG1 1AA" --sort-by most_reduced

# Full property report
property-cli report generate "10 Downing Street, SW1A 2AA" --property-type F

Add --api-url http://localhost:8000 to any command to route through the HTTP API instead of calling core directly.

Use as HTTP API

bash

pip install property-shared[api]  # or: uv add property-shared --extra api
property-api  # starts on port 8000

Interactive docs at http://localhost:8000/docs.

Key endpoints:

GET /v1/ppd/comps?postcode=SW1A+1AA&property_type=F&enrich_epc=true
GET /v1/analysis/yield?postcode=NG1+1AA&property_type=F
GET /v1/analysis/rental?postcode=NG1+1AA&purchase_price=200000
GET /v1/rightmove/search-url?postcode=NG1+1AA&sort_by=newest
GET /v1/calculators/stamp-duty?price=300000&additional_property=true
POST /v1/property/report with { "address": "10 Downing Street, SW1A 2AA" }

Full endpoint list in USER_GUIDE.md.

EPC notes (v1.14.0)

The EPC service moved to a GOV.UK Bearer API. Set EPC_API_TOKEN; the old EPC_API_EMAIL/EPC_API_KEY pair authenticated against a retired host and is not a supported fallback.

What the new upstream supports, and what it does not:

Certificate lookup by certificate number — full detail, one request.
Summary search by postcode — returns address, UPRN (often absent), energy band, registration date and schema type. It does not return energy score, floor area or property type; those exist only on a full certificate.
A postcode selects an area, never a property. Identifying one property needs a UPRN or an address matching a certificate exactly (case, punctuation and a leading Flat/Apartment designator aside). Anything less — no address, no match, or several matches — is refused rather than resolved to a best guess. See USER_GUIDE.md for the CLI and REST surfaces.
Area statistics are limited to the record count and, when the bounded response contains every matching summary, the rating distribution. Property-type breakdown and floor-area statistics are reported as None — unavailable, not zero — because producing them would mean one request per certificate.
Coverage is England and Wales. Scotland, Northern Ireland and the Channel Islands return "no certificates found": a coverage boundary, not a statement about a property.
Pagination is not a stable snapshot. Responses carry complete, duplicates_removed and unusable_rows; no operation claims a complete harvest of an area.
Ambiguous address matches are refused rather than resolved to an arbitrary neighbouring certificate.

search_all_by_postcode() is unsupported — use search_summaries() for candidate discovery, then get_certificate() for the one you need.

Environment Variables

Create a .env file in the repo root (it is gitignored) with the variables you need.

Leave optional variables out entirely rather than assigning them empty. KEY= sets an empty string, which is not the same as unset: os.getenv("KEY", "default") returns "", so the default never applies. This bit the EPC live tests, which sent an empty postcode upstream.

Key variables:

Variable	Required For	Description
`EPC_API_TOKEN`	EPC lookups	Bearer token from GOV.UK EPC data
`EPC_API_EMAIL`	(deprecated)	Retired service; parsed only to raise a configuration error
`EPC_API_KEY`	(deprecated)	Retired service; not a supported fallback
`COMPANIES_HOUSE_API_KEY`	Company search	Free key from Companies House
`RIGHTMOVE_DELAY_SECONDS`	No (default 0.6s)	Rate limit delay for Rightmove scraping
`OPENAI_API_KEY`	Planning scraper	Vision-guided planning portal scraper

Land Registry PPD and Rightmove work without credentials.

Development

bash

# Install dependencies (dev tooling installs by default via [dependency-groups])
uv sync

# Run API with reload
uv run --extra api uvicorn app.main:app --reload

# Full validation (lockfile check, pre-commit, all extras, full suite) —
# same entrypoint CI and the release gate use
./scripts/validate.sh

# + live integration tests (real network calls)
RUN_LIVE_TESTS=1 ./scripts/validate.sh

Deployed at https://property-shared.fly.dev with API docs at /docs and MCP endpoint at /mcp.

property_url_or_id	string	required
include_images	boolean	optional
max_images	integer	optional

UK Property Data

MCP Server: io.github.paulieb89/property-shared

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

property_comps

property_yield

rental_analysis

property_epc

property_epc_search

epc_certificate

stamp_duty

rightmove_search

rightmove_listing

property_blocks

company_search

planning_search

ppd_transactions

Property Shared

What You Get

Skills & Plugins

Use as MCP Server

Install

Use as a Python Library

Use as CLI

Use as HTTP API

EPC notes (v1.14.0)

Environment Variables

Development

Install

Related servers

postcode	string	required
months	integer	optional
property_type	any	optional
transaction_category	any	optional
filter_outliers	boolean	optional
search_level	string	optional
address	any	optional
limit	integer	optional
enrich_epc	boolean	optional

price	integer	required
additional_property	boolean	optional
first_time_buyer	boolean	optional
non_resident	boolean	optional

postcode	string	required	UK postcode (e.g. "NG1 2NS").
months	integer	optional	PPD sale lookback period (default 24).
search_level	string	optional	PPD search granularity — "postcode", "sector" (default), or "district".
property_type	any	optional	Filter sales by type. None (default) = residential set (F+D+S+T). Pass "F"/"D"/"S"/"T"/"O" for one type, "ALL" for firehose.
auto_escalate	boolean	optional	Widen the PPD search area on thin markets — postcode→ sector→district. Default True. Set False for strict-locality only.