使用说明

房地产MCP服务器

MCP（模型上下文协议）服务器，使AI代理能够搜索、检索和生成房地产列表的内容。

https://github.com/user-attachments/assets/94df4c91-ac30-44c3-a95c-adae11573cfc

特性

3个MCP工具：搜索属性、获取详细信息、生成列表内容
MCP资源：每日新上市摘要(realestate://listings/today)
MCP提示：营销电子邮件生成器(marketing-email)
承载令牌身份验证：安全的API访问
PostgreSQL后端：高效的范围查询，JSONB支持
异步架构：全程无阻塞I/O

为什么是这个堆栈？

选择	基本原理
PostgreSQL	高效的价格范围查询(`WHERE price BETWEEN x AND y`)JSONB具有灵活的功能，成熟的异步支持，通过pgvector轻松包含语义搜索，可以部署到AWS RDS
官方MCP SDK	符合规范，本地资源/提示，Anthropic主动维护
紫外线	比pip快10-100x，可靠的锁文件，现代Python打包
FastMCP+FastAPI	基于装饰器的工具、SSE传输、熟悉的异步模式

快速开始

尝试现场演示（最快）

npx -y @modelcontextprotocol/inspector \
  --sse "https://real-estate-mcp-production.up.railway.app/mcp/sse" \
  --header "Authorization: Bearer demo-token-12345"

无需设置！看现场演示了解更多详情。

使用Docker Compose（推荐）

# Clone and start
git clone <repo>
cd real-estate-mcp

# Configure environment (required)
cp .env.example .env
# Edit .env with your own values (API_TOKEN, database credentials, etc.)

# Start everything (db + seed + server)
docker-compose up -d

# Check health
curl http://localhost:8000/health

# Test with MCP Inspector
npx -y @modelcontextprotocol/inspector --config mcp-inspector.json --server real-estate-mcp

这个命令启动PostgreSQL，用示例数据为数据库添加种子，并启动MCP服务器。

⚠️ 重要：从不承诺 .env 版本控制。这 .env.example 文件是一个带有占位符值的模板。

本地开发

# Prerequisites: uv, Docker (for PostgreSQL)

# 1. Install uv (if not installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Create environment
uv venv
source .venv/bin/activate

# 3. Install dependencies
uv sync --all-extras

# 4. Configure environment
cp .env.example .env
# Edit .env: set DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/realestate

# 5. Start PostgreSQL only
docker-compose up -d db

# 6. Seed database
uv run python -m src.db.seed

# 7. Run server
uv run uvicorn src.main:app --reload --port 8000

# 8. Lint/Format
uv run ruff check . --fix
uv run ruff format .

# 9. Run tests
uv run pytest -v

API身份验证

所有MCP端点都需要Bearer令牌：

# Demo token for testing
Authorization: Bearer demo-token-12345

可用的MCP工具

工具	描述	参数
`search_properties`	使用筛选器搜索	`city`, `min_price`, `max_price`, `status`
`get_property_details`	获取完整的房产数据	`property_id` （必填）
`generate_listing_content`	生成SEO HTML	`property_id`, `target_language`, `tone`

工具调用示例

// Search for apartments in Lisbon under €700k
{
  "name": "search_properties",
  "arguments": {
    "city": "Lisbon",
    "max_price": 700000,
    "status": "available"
  }
}

// Get property details
{
  "name": "get_property_details",
  "arguments": {
    "property_id": "11111111-1111-1111-1111-111111111111"
  }
}

// Generate listing content
{
  "name": "generate_listing_content",
  "arguments": {
    "property_id": "11111111-1111-1111-1111-111111111111",
    "target_language": "en",
    "tone": "luxury"
  }
}

可用MCP资源

资源URI	描述
`realestate://listings/today`	每日新上市摘要（过去24小时）

可用MCP提示

提示	描述	参数
`marketing-email`	生成房地产营销电子邮件	`property_id`

MCP检验员测试

这 MCP 检查员提供用于测试的交互式UI：

使用配置文件（推荐）

# Run inspector with the included config
npx -y @modelcontextprotocol/inspector --config mcp-inspector.json --server real-estate-mcp

这将启动检查员 http://localhost:6274 预先配置了身份验证。

手动连接

或者，通过SSE手动连接：

npx -y @modelcontextprotocol/inspector sse http://localhost:8000/mcp/sse \
  --header "Authorization: Bearer demo-token-12345"

脚本编写的CLI模式

以编程方式测试工具：

# List all available tools
npx -y @modelcontextprotocol/inspector --cli \
  --config mcp-inspector.json --server real-estate-mcp \
  --method tools/list

# Search for properties in Lisbon
npx -y @modelcontextprotocol/inspector --cli \
  --config mcp-inspector.json --server real-estate-mcp \
  --method tools/call --tool-name search_properties \
  --tool-arg city=Lisbon --tool-arg status=available

# Get property details
npx -y @modelcontextprotocol/inspector --cli \
  --config mcp-inspector.json --server real-estate-mcp \
  --method tools/call --tool-name get_property_details \
  --tool-arg property_id=11111111-1111-1111-1111-111111111111

检查器显示：

所有已注册的工具及其模式
可用资源
提示模板
交互式测试界面
请求/响应历史记录

现场演示

在Railway上部署了一个公共实例进行测试：


统一资源定位符	`https://real-estate-mcp-production.up.railway.app/mcp/sse`
代币	`demo-token-12345`

现在试试

# Connect via MCP Inspector (no installation required)
npx -y @modelcontextprotocol/inspector \
  --sse "https://real-estate-mcp-production.up.railway.app/mcp/sse" \
  --header "Authorization: Bearer demo-token-12345"

这将在以下位置打开一个交互式UI http://localhost:6274 您可以在哪里：

浏览所有可用的工具、资源和提示
执行工具调用并查看响应
测试完整的MCP协议

配置您的MCP客户端

将此添加到您的MCP客户端配置中（Claude Desktop、Cursor等）：

{
  "mcpServers": {
    "real-estate": {
      "type": "sse",
      "url": "https://real-estate-mcp-production.up.railway.app/mcp/sse",
      "headers": {
        "Authorization": "Bearer demo-token-12345"
      }
    }
  }
}

无需本地设置，只需URL和令牌！

部署您自己的实例（铁路）

推送到GitHub
将repo连接到铁路
添加PostgreSQL插件
在铁路仪表板中设置环境变量：
- API_TOKEN：你的秘密令牌
- DATABASE_URL：由铁路自动配置
部署！

项目结构

real-estate-mcp/
├── src/
│   ├── main.py                 # FastAPI + FastMCP setup
│   ├── config.py               # Type-safe settings
│   ├── mcp_server.py           # MCP tools, resources, prompts
│   ├── auth.py                 # Bearer token middleware
│   ├── exceptions.py           # Custom MCP-friendly errors
│   ├── services/               # Business logic layer
│   ├── repositories/           # Data access layer
│   ├── models/                 # SQLAlchemy ORM models
│   ├── schemas/                # Pydantic schemas
│   └── db/                     # Database session & seeding
├── templates/                  # Jinja2 templates
├── tests/                      # Unit tests
├── .env.example                # Environment template (copy to .env)
├── mcp-inspector.json          # MCP Inspector config (pre-configured auth)
├── Dockerfile                  # Multi-stage Docker build
├── docker-compose.yml          # Full stack orchestration
├── railway.toml                # Railway deployment config
└── pyproject.toml              # Dependencies & tooling

示例属性

数据库中有8个属性：

城市里斯本、波尔图、卡斯卡伊斯、埃斯托利尔、辛特拉
类型：公寓、别墅、顶层公寓、联排别墅
价格范围：19.5万欧元-12.5万欧元
状态：有售

环境变量

只有在以下情况下才需要这些变量 自己部署/运行服务器。如果您要连接到现有部署，则只需要服务器URL和承载令牌。

变量	描述	默认值
`APP_NAME`	应用程序名称	房地产MCP服务器
`DEBUG`	启用调试模式	false
`API_TOKEN`	身份验证的承载令牌	（必需）
`DATABASE_URL`	PostgreSQL连接URL	（必填）
`POSTGRES_USER`	数据库用户名	（用于docker compose）
`POSTGRES_PASSWORD`	数据库密码	（用于docker compose）
`POSTGRES_DB`	数据库名称	（用于docker compose）
`DB_POOL_SIZE`	连接池大小	5
`DB_MAX_OVERFLOW`	最大溢出连接数	10

许可证

MIT许可证-有关详细信息，请参阅许可证文件。