Real Estate MCP

房地产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

为什么是这个堆栈？

快速开始

尝试现场演示（最快）

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 
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 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资源

可用MCP提示

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上部署了一个公共实例进行测试：

现在试试

# 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和令牌！

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

1. 推送到GitHub
2. 将repo连接到 铁路
3. 添加PostgreSQL插件
4. 在铁路仪表板中设置环境变量：

- API_TOKEN：你的秘密令牌 - DATABASE_URL：由铁路自动配置

1. 部署！

项目结构

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和承载令牌。

许可证

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