# Zoopla MCP Server
[English](./README_EN.md) | 简体中文 | [繁體中文](./README_ZH-TW.md)
用于访问 Zoopla API 的 MCP 服务器。
## 🚀 使用 EMCP 平台快速体验
**[EMCP](https://sit-emcp.kaleido.guru)** 是一个强大的 MCP 服务器管理平台，让您无需手动配置即可快速使用各种 MCP 服务器！
### 快速开始：
1. 🌐 访问 **[EMCP 平台](https://sit-emcp.kaleido.guru)**
2. 📝 注册并登录账号
3. 🎯 进入 **MCP 广场**，浏览所有可用的 MCP 服务器
4. 🔍 搜索或找到本服务器（`bach-zoopla`）
5. 🎉 点击 **"安装 MCP"** 按钮
6. ✅ 完成！即可在您的应用中使用
### EMCP 平台优势：
- ✨ **零配置**：无需手动编辑配置文件
- 🎨 **可视化管理**：图形界面轻松管理所有 MCP 服务器
- 🔐 **安全可靠**：统一管理 API 密钥和认证信息
- 🚀 **一键安装**：MCP 广场提供丰富的服务器选择
- 📊 **使用统计**：实时查看服务调用情况
立即访问 **[EMCP 平台](https://sit-emcp.kaleido.guru)** 开始您的 MCP 之旅！
---
## 简介
这是一个 MCP 服务器，用于访问 Zoopla API。
- **PyPI 包名**: `bach-zoopla`
- **版本**: 1.0.0
- **传输协议**: stdio
## 安装
### 从 PyPI 安装:
```bash
pip install bach-zoopla
```
### 从源码安装:
```bash
pip install -e .
```
## 运行
### 方式 1: 使用 uvx（推荐，无需安装）
```bash
# 运行（uvx 会自动安装并运行）
uvx --from bach-zoopla bach_zoopla
# 或指定版本
uvx --from bach-zoopla@latest bach_zoopla
```
### 方式 2: 直接运行（开发模式）
```bash
python server.py
```
### 方式 3: 安装后作为命令运行
```bash
# 安装
pip install bach-zoopla
# 运行（命令名使用下划线）
bach_zoopla
```
## 配置
### API 认证
此 API 需要认证。请设置环境变量:
```bash
export API_KEY="your_api_key_here"
```
### 环境变量
| 变量名 | 说明 | 必需 |
|--------|------|------|
| `API_KEY` | API 密钥 | 是 |
| `PORT` | 不适用 | 否 |
| `HOST` | 不适用 | 否 |
### 在 Cursor 中使用
编辑 Cursor MCP 配置文件 `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"bach-zoopla": {
"command": "uvx",
"args": ["--from", "bach-zoopla", "bach_zoopla"],
"env": {
"API_KEY": "your_api_key_here"
}
}
}
}
```
### 在 Claude Desktop 中使用
编辑 Claude Desktop 配置文件 `claude_desktop_config.json`:
```json
{
"mcpServers": {
"bach-zoopla": {
"command": "uvx",
"args": ["--from", "bach-zoopla", "bach_zoopla"],
"env": {
"API_KEY": "your_api_key_here"
}
}
}
}
```
## 可用工具
此服务器提供以下工具:
### `propertiesv2list`
List properties for sale or rent with options and filters
**端点**: `GET /properties/v2/list`
**参数**:
- `locationValue` (string) *必需*: The value of geoLabel field returned in .../v2/auto-complete endpoint with listings as search_type. Or the value of name field returned in .../house-prices/v2/get-area (If you are searching by postal code). You must use EXACTLY the value returned by the endpoint. *'listing_id' OR 'area' parameter must be provided to get this endpoint working.
- `locationIdentifier` (string) *必需*: The value of geoIdentifier field returned in .../v2/auto-complete endpoint with listings as search_type. Or the value of id field returned in ..../house-prices/v2/get-area endpoint (If you are searching by postal code). You must use EXACTLY the value returned by the endpoint.
- `category` (string): One of the following residential|commercial
- `furnishedState` (string): One of the following : Any|furnished|part_furnished|unfurnished
- `includeRented` (string): Example value:
- `includeRetirementHomes` (string): Example value:
- `includeSharedAccommodation` (string): Example value:
- `includeSharedOwnership` (string): Example value:
- `includeSold` (string): Example value:
- `isAuction` (string): Example value:
- `petsAllowed` (string): Example value:
- `billsIncluded` (string): Example value:
- `keywords` (string): Any word or term, ex : garden,wooden floors
- `section` (string): One of the following : for-sale|to-rent
- `bedsMax` (number): Max number of bed rooms (1 - 10)
- `bedsMin` (number): Min number of bed rooms (1 - 10)
- `priceMax` (number): Maximum sale or rent price
- `priceMin` (number): Minimum sale or rent price
- `sortOrder` (string): One of the following : newest_listings|highest_price|lowest_price|most_reduced
- `page` (number): The page index for paging purpose
- `radius` (number): The radius (miles) to look for properties (0.25 - 40)
- `priceFrequency` (string): One of the following per_month|per_year
- `newHomes` (string): One of the following : only|exclude
- `added` (string): Recently added. One of the following : 24_hours|3_days|7_days|14_days|30_days
- `propertySubType` (string): Filter properties by category. Ignore OR one of the followings (Separated by comma for multiple options) : park_home,bungalow,farms_land,terraced,flats,semi_detached,detached
- `chainFree` (string): Example value:
- `reducedPriceOnly` (string): Example value:
- `feature` (string): One of the followings : has_balcony_terrace|has_parking_garage|has_garden . Separated by comma for multiple options. Ex : has_balcony_terrace,has_parking_garage,...
- `tenure` (string): One of the followings : share_of_freehold|freehold|leasehold. Ex : freehold,leasehold,...
- `smartTags` (string): One of the followings : condition.needs_modernisation|architecture.period_property|type.cottage|style.modern|attributes.utility_room|attributes.basement|attributes.conservatory|attributes.home_office|attributes.bath|attributes.en_suite|attributes.patio|attributes.kitchen_island. Ex : condition.needs_modernisation,architecture.period_property,...
---
### `house_pricesv2estimate`
Returned list of estimated house prices
**端点**: `GET /house-prices/v2/estimate`
**参数**:
- `geoIdentifier` (string) *必需*: The value of 'urlPath' field returned in .../house-prices/v2/auto-complete endpoint OR the value of 'id' field returned in .../house-prices/v2/get-area endpoint.
- `after` (number): The offset to ignore for paging purpose.
- `first` (number): The number of items per response
---
### `agentsdetail`
Get detailed information of an agent by id
**端点**: `GET /agents/detail`
**参数**:
- `id` (number) *必需*: The value of id field returned in .../agents/list endpoint
---
### `agentslist`
List agents with filters and options
**端点**: `GET /agents/list`
**参数**:
- `location` (string) *必需*: The value of geoIdentifier field returned in .../v2/auto-complete endpoint with listings as search_type. Or the value of id field returned in ..../house-prices/v2/get-area endpoint (If you are searching by postal code). You must use EXACTLY the value returned by the endpoint.
- `search_type` (string): One of the followings : estate-agents|letting-agents|commercial-agents
- `company_name` (string): Search by agent name. Either 'location' or 'company_name' is required. You can ignore 'location' parameter when passing value into 'company_name' parameter.
- `agents_sort` (string): One of the following : a_z|lowest_avg_price|highest_avg_price|shortest_avg_age|longest_avg_age
- `pn` (number): The page index for paging purpose
- `radius` (number): The radius (miles) to look for agents (0.25 - 40)
---
### `house_pricesget_area_stats_deprecated`
Get area stats
**端点**: `GET /house-prices/get-area-stats`
**参数**:
- `property_id` (number) *必需*: The value of property_id field returned in .../house-prices/estimate endpoint.
---
### `house_pricesget_historic_listings_deprecated`
Get historic listings
**端点**: `GET /house-prices/get-historic-listings`
**参数**:
- `property_id` (number) *必需*: The value of property_id field returned in .../house-prices/estimate endpoint.
---
### `house_pricesv2get_area`
Use along with .../house-prices/v2/auto-complete endpoint to get related geo id. For example, geo id of postal code.
**端点**: `GET /house-prices/v2/get-area`
**参数**:
- `geoString` (string) *必需*: Postal code, city, district, ward, area, etc.... Use exact values returned in .../house-prices/v2/auto-complete endpoint for best result
---
### `house_pricesget_running_costs_deprecated`
Get running costs
**端点**: `GET /house-prices/get-running-costs`
**参数**:
- `property_id` (number) *必需*: The value of property_id field returned in .../house-prices/estimate endpoint.
---
### `house_pricesget_market_activity_deprecated`
Get market activity in an area
**端点**: `GET /house-prices/get-market-activity`
**参数**:
- `identifier` (string): The value of suggestions/identifier json object returned in .../auto-complete endpoint with properties as search_type. You must use EXACTLY the value returned by the endpoint.
- `area` (string) *必需*: The value of suggestions/value json object returned in .../auto-complete endpoint with properties as search_type. You must use EXACTLY the value returned by the endpoint.
---
### `house_pricesget_sales_history_deprecated`
Get sales history
**端点**: `GET /house-prices/get-sales-history`
**参数**:
- `property_id` (number) *必需*: The value of property_id field returned in .../house-prices/estimate endpoint.
---
### `propertiesget_nearby_deprecated`
Get nearest points of interest
**端点**: `GET /properties/get-nearby`
**参数**:
- `listing_id` (number) *必需*: The value of listing_id field returned in .../properties/list endpoint
---
### `propertiesv2detail`
Get property detail
**端点**: `GET /properties/v2/detail`
**参数**:
- `listingId` (number) *必需*: The value of listingId field returned in .../properties/v2/list endpoint
---
### `propertiesget_broadband_deprecated`
Get broadband information
**端点**: `GET /properties/get-broadband`
**参数**:
- `listing_id` (number) *必需*: The value of listing_id field returned in .../properties/list endpoint
---
### `propertiesget_running_costs_deprecated`
Get running costs
**端点**: `GET /properties/get-running-costs`
**参数**:
- `listing_id` (number) *必需*: The value of listing_id field returned in .../properties/list endpoint
- `category` (string): One of the following residential|commercial
- `section` (string): One of the following for-sale|to-rent
---
### `propertieslist_deprecated`
List properties for sale or rent with options and filters
**端点**: `GET /properties/list`
**参数**:
- `area` (string) *必需*: The value of suggestions/value json object returned in .../auto-complete endpoint with listings as search_type. You must use EXACTLY the value returned by the endpoint. *'listing_id' OR 'area' parameter must be provided to get this endpoint working.
- `identifier` (string): The value of suggestions/identifier json object returned in .../auto-complete endpoint with listings as search_type. You must use EXACTLY the value returned by the endpoint.
- `listing_id` (string): The value of listing_id field returned right in this endpoint. *'listing_id' OR 'area' parameter must be provided to get this endpoint working.
- `category` (string): One of the following residential|commercial
- `created_since` (string): The date time from which properties added. The format must be yyyy-MM-dd HH:mm:ss, Ex : 2020-09-16 15:00:00
- `furnished` (string): One of the following furnished|part_furnished|unfurnished
- `include_featured_properties` (number): One of the following 1 | 0
- `include_rented` (number): One of the following 1 | 0
- `include_retirement_homes` (string): One of the following yes | no
- `include_shared_accommodation` (string): One of the following yes | no
- `include_shared_ownership` (string): One of the following yes | no
- `include_sold` (number): One of the following 1 | 0
- `keywords` (string): Any word or term, ex : garden,wooden floors
- `listing_status` (string): One of the following sale | rent
- `maximum_beds` (number): Max number of bed rooms (1 - 10)
- `minimum_beds` (number): Min number of bed rooms (1 - 10)
- `maximum_price` (number): Maximum sale or rent price
- `minimum_price` (number): Minimum sale or rent price
- `order_by` (string): One of the following age|price|price_change|view_count
- `ordering` (string): One of the following ascending|descending
- `page_number` (number): The page index for paging purpose
- `page_size` (number): The number of items per response (max 40)
- `property_type` (string): One of the following and separated by comma for multiple values : flats|farms_land|terraced|semi_detached|detached|bungalow|park_home|offices|retail|industrial|hospitality|land
- `radius` (number): The radius (miles) to look for properties (1 - 40)
- `pets_allowed` (string): One of the following yes | no
- `price_frequency` (string): One of the following per_month|per_year
- `step_back_used` (number): One of the following 1 | 0
- `bills_included` (string): One of the following yes | no
- `floor_area_max` (number): Maximum floor area, only use with commercial category.
- `floor_area_min` (number): Minimum floor area, only use with commercial category.
- `floor_area_units` (string): One of the following sq_feet|sq_metres
- `new_homes` (string): One of the following yes | no
---
### `propertiesget_area_stats_deprecated`
Get area stats
**端点**: `GET /properties/get-area-stats`
**参数**:
- `listing_id` (number) *必需*: The value of listing_id field returned in .../properties/list endpoint
---
### `v2auto_complete`
Get auto complete suggestion by term or phrase
**端点**: `GET /v2/auto-complete`
**参数**:
- `locationPrefix` (string) *必需*: Example value: greenwich
---
### `auto_complete_deprecated`
Get auto complete suggestion by term or phrase
**端点**: `GET /auto-complete`
**参数**:
- `search_term` (string) *必需*: Example value: greenwich
- `search_type` (string): One of the following properties|listings. Use listings value to get suggestion for .../properties/list endpoint. Use properties value to get suggestion for .../house-prices/estimate endpoint.
---
### `house_pricesv2detail`
Get property price detailed information
**端点**: `GET /house-prices/v2/detail`
**参数**:
- `uprn` (number) *必需*: The value of "uprn" field returned in .../house-prices/v2/estimate endpoint.
---
### `house_pricesv2auto_complete`
Get suggestions by term or phrase about city, country, area,etc...
**端点**: `GET /house-prices/v2/auto-complete`
**参数**:
- `addressPartial` (string) *必需*: City, district, ward, area, etc....
---
### `house_pricesget_points_of_interest_deprecated`
Get nearest points of interest
**端点**: `GET /house-prices/get-points-of-interest`
**参数**:
- `property_id` (number) *必需*: The value of property_id field returned in .../house-prices/estimate endpoint.
---
### `house_pricesestimate_deprecated`
Returned list of estimated house prices
**端点**: `GET /house-prices/estimate`
**参数**:
- `identifier` (string): The value of suggestions/identifier json object returned in .../auto-complete endpoint with properties as search_type. You must use EXACTLY the value returned by the endpoint.
- `area` (string) *必需*: The value of suggestions/value json object returned in .../auto-complete endpoint with properties as search_type. You must use EXACTLY the value returned by the endpoint.
- `order_by` (string): One of the following price_paid|last_sold|address|estimated_value
- `ordering` (string): One of the following ascending|descending
- `page_number` (number): The page index for paging purpose
- `page_size` (number): The number of items per response (max 40)
- `property_type` (string): One of the following detached|flat|terraced|semi_detached
---
## 技术栈
- **传输协议**: stdio
- **HTTP 客户端**: httpx
## 许可证
MIT License - 详见 [LICENSE](./LICENSE) 文件。
## 开发
此服务器由 [API-to-MCP](https://github.com/BACH-AI-Tools/api-to-mcp) 工具生成。
版本: 1.0.0