Skip to main content
Glama
Property Price Search MCP Server

Property Price Search MCP Server

by joemclo

Property Price Search MCP Server

A Model Context Protocol (MCP) server that allows users to search for property prices by postcode using the HM Land Registry's SPARQL endpoint.

Features

  • Search property prices by postcode or street/city combination

  • Filter results by price range, property type, and date range

  • Connect to HM Land Registry's public SPARQL endpoint

  • Implements MCP stdio transport for IDE integration

  • TypeScript implementation with full type safety

  • Comprehensive test suite

  • Local postcode lookup & nearest-neighbour tool using Ordnance Survey Code-Point Open (downloaded separately)

  • CLI interface for direct usage

Related MCP server: UK Property Intelligence

Prerequisites

  • Node.js >= 20

  • npm >= 7

Installation

Global Installation

npm install -g property-prices-mcp

Local Installation

npm install property-prices-mcp

Usage

As an MCP Server

This server is designed to be used with MCP clients (like Claude Desktop, IDEs with MCP support, etc.). Configure your MCP client to use this server via stdio transport:

{
  "mcpServers": {
    "property-prices": {
      "command": "property-prices-mcp"
    }
  }
}

Once connected, you can use the search-property-prices tool with the following parameters:

{
  "postcode": "SW1A 1AA",
  "minPrice": 1000000,
  "propertyType": "flat",
  "limit": 5
}

You can also use the lookup-postcodes tool (built on Ordnance Survey Code-Point Open) to resolve postcodes and find nearby postcodes:

{
  "postcode": "SW1A 1AA",
  "radiusMeters": 2000,
  "limit": 5
}

Note: The Code-Point Open CSVs are not bundled. Download them once, then build the local postcode database:

  • npm run setup:postcodes (downloads + builds), or

  • npm run fetch:codepo then npm run build:postcodes

Manual download: https://api.os.uk/downloads/v1/products/CodePointOpen/downloads?area=GB&format=CSV&redirect Contains Ordnance Survey data © Crown copyright and database right, Royal Mail data © Royal Mail copyright and database right, and National Statistics data © Crown copyright and database right.

Command Line Interface

For testing or direct usage:

property-prices-mcp

Usage Notes

Case Sensitivity

The UK Land Registry data is case-sensitive for street names and city names. However, this MCP automatically converts these parameters to uppercase before sending to the Land Registry API, so you can use any case in your searches.

Example:

"Cherry Drive" and "CHERRY DRIVE" will both work correctly.

Search Parameters

The server accepts the following search parameters:

Parameter

Type

Description

Default

postcode

string

UK postcode to search

-

street

string

Street name

-

city

string

City name

-

minPrice

number

Minimum property price

-

maxPrice

number

Maximum property price

-

propertyType

string

One of: detached, semi-detached, terraced, flat, other

-

fromDate

string

Start date (YYYY-MM-DD)

-

toDate

string

End date (YYYY-MM-DD)

-

limit

number

Maximum number of results

10

offset

number

Number of results to skip

0

sortBy

string

Sort by 'date' or 'price'

'date'

sortOrder

string

Sort order 'asc' or 'desc'

'desc'

Response Format

The API returns results in the following format:

interface PropertyPrice {
  price: number;
  date: string;
  postcode: string;
  propertyType: 'detached' | 'semi-detached' | 'terraced' | 'flat' | 'other';
  street: string;
  city: string;
  paon?: string;
  saon?: string;
}

interface SearchResponse {
  properties: PropertyPrice[];
  total: number;
  offset: number;
  limit: number;
}

Error Handling

The server returns standard HTTP status codes:

  • 200: Successful request

  • 400: Invalid parameters

  • 404: No results found

  • 500: Server error

Error responses include a message explaining the error:

{
  "error": "Invalid postcode format"
}

Development

  1. Clone the repository:

    git clone https://github.com/joemclo/property-prices-mcp.git
    cd property-prices-mcp
  2. Install dependencies:

    npm install
  3. Build the project:

    npm run build
  4. Run tests:

    npm test                  # Run unit tests (fast, mocked)
    npm run test:unit        # Run unit tests only
    npm run test:e2e         # Run e2e tests (requires internet, hits real API)
    npm run test:all         # Run all tests including e2e

    Note: E2E tests make real API calls to the HM Land Registry SPARQL endpoint and are skipped by default. They require internet connectivity and may fail in sandboxed environments.

  5. Start in development mode:

    npm run dev

Testing

This project uses a three-tier testing approach:

Test Structure

src/__tests__/
├── unit/              # Unit tests (fast, all mocked)
│   ├── queries.test.ts
│   ├── sparqlService.test.ts
│   └── mcpTool.test.ts
└── e2e/               # End-to-end tests (slow, real API calls)
    └── propertySearch.e2e.test.ts

Running Tests

  • Unit tests (default): Fast tests with mocked dependencies

    npm test           # or npm run test:unit
  • E2E tests: Real API calls to HM Land Registry

    npm run test:e2e

    Note: E2E tests are skipped by default and require:

  • All tests: Run both unit and e2e tests

    npm run test:all

Manual Testing

For ad-hoc testing with real data:

npm run test-mcp

Troubleshooting

Common Issues

  1. SPARQL Endpoint Connection Issues

    • Check your internet connection

    • Verify the HM Land Registry endpoint is available

    • Ensure your IP is not being rate limited

  2. Invalid Postcode Format

    • Ensure postcodes are in the correct UK format

    • Remove any extra spaces

    • Use uppercase letters

  3. No Results Found

    • Try broadening your search criteria

    • Check if the date range is too narrow

    • Verify the postcode exists

Contributing

Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

Changelog

See CHANGELOG.md for a list of changes and version history.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Available Tools

2 tools
lookup-postcodesA

Look up UK postcodes (Code-Point Open) and find nearest neighbours using OSGB36 eastings/northings. Provide either postcode or both easting and northing as the center. Optional: radiusMeters (meters), limit (default 10), includeSelf (default false), adminDistrict filter. Returns { center, postcodes: [{ postcode, easting, northing, positionalQuality, countryCode, adminDistrictCode, distanceMeters }], total }. Requires a local database built from the bundled codepo_gb CSVs via npm run build:postcodes.

Inputs: postcode, easting, northing, limit, +3 more.

search-property-pricesA

Search HM Land Registry price-paid data. Provide either postcode or both street and city (case-insensitive; uppercased for the query). Optional filters: minPrice/maxPrice (GBP), propertyType (detached | semi-detached | terraced | flat | other), fromDate/toDate (YYYY-MM-DD), limit/offset (pagination), sortBy (date | price), sortOrder (asc | desc). Returns JSON: { properties: [{ price, date, postcode, propertyType, street, city, paon?, saon? }], total, offset, limit }, where paon is the Primary Addressable Object Name (e.g., house number/name) and saon is the Secondary Addressable Object Name (e.g., flat/unit/apartment).

Inputs: postcode, street, city, minPrice, +8 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have clearly distinct purposes: one looks up postcode data and finds nearest neighbours, while the other searches property price data. There is no overlap in functionality, making it easy for an agent to choose the correct tool based on the task.

    Naming Consistency5/5

    Both tools follow a consistent verb_noun pattern with hyphens: 'lookup-postcodes' and 'search-property-prices'. This naming convention is predictable and readable throughout the set.

    Tool Count2/5

    With only 2 tools, the server feels under-scoped for a property price search domain. While the tools cover postcode lookup and price search, there are likely missing operations such as filtering by property features or retrieving detailed property records, making the surface thin and incomplete.

    Completeness2/5

    The server lacks comprehensive coverage for property price search. It includes basic lookup and search functions but misses essential operations like updating or deleting data, advanced analytics, or integration with other property databases, which could lead to agent failures in complex tasks.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      Enables access to UK property listings, price estimates, agent information, and market data through the Zoopla API for searching properties for sale or rent with detailed filters and analytics.
      22
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to query UK property data including EPCs, sale history, planning, flood risk, council tax, demographics, and more via the Homedata API.
      18
      32 PyPI
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables natural language queries about UK postcodes and vehicles, including flood risk, crime rate, broadband coverage, property prices, MOT history, and ULEZ compliance.
      4
      38 npm
      MIT