{
  "markdown": "# Property Shared\n\n<!-- mcp-name: io.github.paulieb89/property-shared -->\n\n[![property-shared MCP server](https://glama.ai/mcp/servers/paulieb89/property-shared/badges/card.svg)](https://glama.ai/mcp/servers/paulieb89/property-shared)\n\nUK 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.\n\nUse it as a **Python library**, **CLI**, **HTTP API**, or **MCP server**.\n\n## What You Get\n\n| Data Source | What It Returns |\n|-------------|-----------------|\n| **Land Registry PPD** | Sold prices, dates, property types, area comps with median/percentiles |\n| **EPC (GOV.UK)** | Energy ratings, floor area, heating costs. England & Wales only. Certificate lookup and summary search — see EPC notes below |\n| **Rightmove** | Current listings (sale + rent), prices, agents, listing details |\n| **Yield Analysis** | Gross yield from PPD sales + Rightmove rentals combined |\n| **Stamp Duty** | SDLT calculation with April 2025 bands, BTL surcharge, FTB relief |\n| **Block Analyzer** | Groups flat sales by building to spot investor exits |\n| **Planning** | Local council planning portal lookup (99 verified councils, stdio only) |\n| **Companies House** | Company search and lookup by name or number |\n\n## Skills & Plugins \n\nProperty 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  \n\n\n## Use as MCP Server\n\nNo install required — paste the URL into your MCP client config and go.\n\n**Claude Code, Cursor, any MCP client:**\n\n```json\n{\n  \"mcpServers\": {\n    \"property-shared\": {\n      \"type\": \"http\",\n      \"url\": \"https://property-shared.fly.dev/mcp\"\n    }\n  }\n}\n```\n\n## Install\n\n```bash\npip install property-shared\n\n# or with uv\nuv add property-shared\n```\n\nExtras: `[cli]` for CLI, `[api]` for HTTP server.\n\n```bash\npip install property-shared[cli]\n# or\nuv add property-shared --extra cli\n```\n\n## Use as a Python Library\n\n```python\nfrom property_core import PPDService, calculate_yield, calculate_stamp_duty\n\n# Get comparable sales for a postcode\ncomps = PPDService().comps(\"SW1A 1AA\", months=24, property_type=\"F\")\nprint(f\"Median flat price: {comps.median:,}\")\n\n# Calculate rental yield\nimport asyncio\nresult = asyncio.run(calculate_yield(\"NG1 1AA\", property_type=\"F\"))\nprint(f\"Gross yield: {result.gross_yield_pct}%\")\n\n# Stamp duty\nsdlt = calculate_stamp_duty(250000, additional_property=True)\nprint(f\"SDLT: {sdlt.total_sdlt:,.0f} ({sdlt.effective_rate}%)\")\n```\n\nAll models are available at top level:\n```python\nfrom property_core import (\n    PPDTransaction, PPDCompsResponse, EPCData,\n    RightmoveListing, RightmoveListingDetail,\n    PropertyReport, YieldAnalysis, RentalAnalysis,\n    BlockAnalysisResponse, CompanyRecord, StampDutyResult,\n)\n```\n\nInterpretation helpers (core returns numbers, you decide how to label them):\n```python\nfrom property_core import classify_yield, classify_data_quality, generate_insights\n```\n\n## Use as CLI\n\n```bash\npip install property-shared[cli]  # or: uv add property-shared --extra cli\n\n# Comparable sales\nproperty-cli ppd comps \"SW1A 1AA\" --months 24 --property-type F\n\n# Rental yield\nproperty-cli analysis yield \"NG1 1AA\" --property-type F\n\n# Stamp duty\nproperty-cli calc stamp-duty 300000\n\n# Rightmove search (with sort)\nproperty-cli rightmove search-url \"NG1 1AA\" --sort-by most_reduced\n\n# Full property report\nproperty-cli report generate \"10 Downing Street, SW1A 2AA\" --property-type F\n```\n\nAdd `--api-url http://localhost:8000` to any command to route through the HTTP API instead of calling core directly.\n\n## Use as HTTP API\n\n```bash\npip install property-shared[api]  # or: uv add property-shared --extra api\nproperty-api  # starts on port 8000\n```\n\nInteractive docs at `http://localhost:8000/docs`.\n\nKey endpoints:\n- `GET /v1/ppd/comps?postcode=SW1A+1AA&property_type=F&enrich_epc=true`\n- `GET /v1/analysis/yield?postcode=NG1+1AA&property_type=F`\n- `GET /v1/analysis/rental?postcode=NG1+1AA&purchase_price=200000`\n- `GET /v1/rightmove/search-url?postcode=NG1+1AA&sort_by=newest`\n- `GET /v1/calculators/stamp-duty?price=300000&additional_property=true`\n- `POST /v1/property/report` with `{ \"address\": \"10 Downing Street, SW1A 2AA\" }`\n\nFull endpoint list in [USER_GUIDE.md](USER_GUIDE.md).\n\n## EPC notes (v1.14.0)\n\nThe EPC service moved to a GOV.UK Bearer API. Set `EPC_API_TOKEN`; the old\n`EPC_API_EMAIL`/`EPC_API_KEY` pair authenticated against a retired host and is\nnot a supported fallback.\n\nWhat the new upstream supports, and what it does not:\n\n- **Certificate lookup** by certificate number — full detail, one request.\n- **Summary search** by postcode — returns address, UPRN (often absent), energy\n  band, registration date and schema type. It does **not** return energy score,\n  floor area or property type; those exist only on a full certificate.\n- **A postcode selects an area, never a property.** Identifying one property\n  needs a UPRN or an address matching a certificate exactly (case, punctuation\n  and a leading `Flat`/`Apartment` designator aside). Anything less — no address,\n  no match, or several matches — is refused rather than resolved to a best guess.\n  See [USER_GUIDE.md](USER_GUIDE.md) for the CLI and REST surfaces.\n- **Area statistics** are limited to the record count and, when the bounded\n  response contains every matching summary, the rating distribution.\n  Property-type breakdown and floor-area statistics are reported as `None` —\n  unavailable, not zero — because producing them would mean one request per\n  certificate.\n- **Coverage is England and Wales.** Scotland, Northern Ireland and the Channel\n  Islands return \"no certificates found\": a coverage boundary, not a statement\n  about a property.\n- **Pagination is not a stable snapshot.** Responses carry `complete`,\n  `duplicates_removed` and `unusable_rows`; no operation claims a complete\n  harvest of an area.\n- **Ambiguous address matches are refused** rather than resolved to an arbitrary\n  neighbouring certificate.\n\n`search_all_by_postcode()` is unsupported — use `search_summaries()` for\ncandidate discovery, then `get_certificate()` for the one you need.\n\n## Environment Variables\n\nCreate a `.env` file in the repo root (it is gitignored) with the variables you need.\n\n> **Leave optional variables out entirely rather than assigning them empty.**\n> `KEY=` sets an empty string, which is not the same as unset: `os.getenv(\"KEY\",\n> \"default\")` returns `\"\"`, so the default never applies. This bit the EPC live\n> tests, which sent an empty postcode upstream.\n\nKey variables:\n\n| Variable | Required For | Description |\n|----------|-------------|-------------|\n| `EPC_API_TOKEN` | EPC lookups | Bearer token from [GOV.UK EPC data](https://get-energy-performance-data.communities.gov.uk/) |\n| `EPC_API_EMAIL` | *(deprecated)* | Retired service; parsed only to raise a configuration error |\n| `EPC_API_KEY` | *(deprecated)* | Retired service; not a supported fallback |\n| `COMPANIES_HOUSE_API_KEY` | Company search | Free key from [Companies House](https://developer.company-information.service.gov.uk/) |\n| `RIGHTMOVE_DELAY_SECONDS` | No (default 0.6s) | Rate limit delay for Rightmove scraping |\n| `OPENAI_API_KEY` | Planning scraper | Vision-guided planning portal scraper |\n\nLand Registry PPD and Rightmove work without credentials.\n\n## Development\n\n```bash\n# Install dependencies (dev tooling installs by default via [dependency-groups])\nuv sync\n\n# Run API with reload\nuv run --extra api uvicorn app.main:app --reload\n\n# Full validation (lockfile check, pre-commit, all extras, full suite) —\n# same entrypoint CI and the release gate use\n./scripts/validate.sh\n\n# + live integration tests (real network calls)\nRUN_LIVE_TESTS=1 ./scripts/validate.sh\n```\n\nDeployed at `https://property-shared.fly.dev` with API docs at `/docs` and MCP endpoint at `/mcp`.\n",
  "bytes": 7994,
  "sha": "c4ff317bcecc3aa6af043a5bc7ff368e264606d6728f9d2728666675314cbe5d",
  "repo_slug": "paulieb89/property-shared",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_paulieb89_property_shared_6d381395/readme"
}