Propstack Mcp Server

Propstack MCP Server

将 AI 助手（Claude、ChatGPT）连接到您的 Propstack 房地产 CRM。

将 AI 助手连接到您的 Propstack CRM — 管理联系人、搜索房源、维护交易、安排看房并创建搜索档案，全部通过语音或聊天完成。

您可以做什么

• 联系人管理 — 搜索、创建、更新联系人并为其添加标签，同时跟踪 GDPR 状态
• 房源搜索与管理 — 按价格、房间数、面积、状态筛选；创建和更新房源
• 交易流程 — 创建交易、推进交易阶段、跟踪赢单率和输单率
• 买家匹配 — 根据自然语言创建搜索档案（“柏林 3 室，最高 40 万，带阳台”），并自动匹配新房源
• 任务与日历 — 记录通话备注、设置跟进提醒、安排看房
• 电子邮件 — 发送与联系人和房源关联的模板邮件
• 360 度联系人视图 — 每次通话前获取完整简报
• 交易流程仪表板 — 查看各阶段的交易数量和金额，以及停滞交易提醒
• 潜在客户接入 — 一次通话即可完成的工作流：去重、创建联系人、记录备注、创建交易、设置提醒

数据保护（DSGVO）： 使用此服务会将您 Propstack CRM 中的个人数据发送到您连接的大模型（Claude、ChatGPT、……）。您（Propstack 客户）仍是数据控制者。有关责任、法律依据、fields 数据最小化参数以及自动化决策的说明，请参阅 数据保护（DSGVO）。

快速开始

1. 设置您的 API 密钥

export PROPSTACK_API_KEY=your_api_key_here

2a. Claude Desktop

将以下内容添加到您的 Claude Desktop 配置文件（claude_desktop_config.json）中：

{
  "mcpServers": {
    "propstack": {
      "command": "npx",
      "args": ["-y", "propstack-mcp-server"],
      "env": {
        "PROPSTACK_API_KEY": "your_api_key_here"
      }
    }
  }
}

2b. Claude Code（CLI）

将以下内容添加到您项目的 .mcp.json 中：

{
  "mcpServers": {
    "propstack": {
      "command": "npx",
      "args": ["-y", "propstack-mcp-server"],
      "env": {
        "PROPSTACK_API_KEY": "your_api_key_here"
      }
    }
  }
}

2c. ChatGPT 和 claude.ai（网页 / 移动端）

这些客户端只能通过 HTTPS URL 连接到远程 MCP 服务。它们 无法启动本地 npx 命令，因此不能直接添加此服务——请改用 Claude Desktop、Claude Code、Cursor 或其他本地客户端。

如果您需要使用 ChatGPT 或 claude.ai 应用，此服务必须运行在经过身份验证的 HTTPS 端点后。请勿通过开放隧道或未经身份验证的 stdio-to-HTTP 桥接服务公开它：任何拥有该 URL 的人都能使用您的 API 密钥，获得 CRM 的完整读写权限。如果您需要托管部署，请提交 issue。

2d. Cursor IDE

1. 打开设置（Ctrl+,）→ 搜索“MCP”
2. 编辑 MCP Servers JSON，或在项目根目录 / .cursor/ 中添加 mcp.json

选项 A — 本地项目（运行 npm run build 后）：

{
  "mcpServers": {
    "propstack": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "C:/Users/you/path/to/propstack_mcp",
      "env": {
        "PROPSTACK_API_KEY": "your_api_key_here"
      }
    }
  }
}

也可以在项目根目录中使用 .env——服务会自动加载该文件；您可以省略 env 块。

选项 B — npx（已发布的软件包，或通过 npx 运行本地版本）：

{
  "mcpServers": {
    "propstack": {
      "command": "npx",
      "args": ["-y", "propstack-mcp-server"],
      "env": {
        "PROPSTACK_API_KEY": "your_api_key_here"
      }
    }
  }
}

2e. 直接运行

npm install propstack-mcp-server
PROPSTACK_API_KEY=your_key npx propstack-mcp-server

API 密钥

获取您的 Propstack API 密钥：

1. 登录 crm.propstack.de
2. 前往 Verwaltung > API-Schluessel（管理 > API 密钥）
3. 创建或复制您的 V1 API 密钥

注意： API 密钥决定了权限。请确保已为所需端点启用读写权限。

可用工具（56）

联系人

工具	描述
search_contacts	按姓名、电子邮件、电话、状态、标签、经纪人、GDPR 状态和自定义字段搜索及筛选联系人
get_contact	获取单个联系人的完整详情及相关数据
create_contact	创建新联系人（按电子邮件自动去重）
update_contact	更新联系人详情、标签、GDPR 状态及经纪人分配
delete_contact	软删除联系人（保留在 30 天回收站中）
get_contact_sources	列出潜在客户来源（ImmoScout24、网站、推荐等）
search_contacts_by_phone	按电话号码查找联系人（不受格式影响）

房产（Objekte）

工具	描述
search_properties	使用 11 种范围筛选条件、17 个排序字段和自定义字段筛选条件搜索房产
get_property	获取房产的完整详情，包括媒体、自定义字段、能源证书、设备、布局、费用和营销字段
create_property	创建新的房源，包括德国住宅房源说明所需字段（能源证书、设备、费用）
update_property	更新价格、状态、描述、经纪人分配和德国住宅房源说明所需字段
get_property_statuses	列出房产状态（Verfuegbar、Reserviert、Verkauft 等）

任务（Aufgaben & Notizen）

工具	描述
create_task	创建备注、待办事项、预约或取消事项（多态）
update_task	标记为已完成、重新安排时间、更新备注
get_task	获取任务详情及关联的联系人、房产和项目

交易（Pipeline）

工具	描述
search_deals	按阶段、Pipeline、类别、经纪人和意向评分搜索交易
create_deal	在某个 Pipeline 阶段将联系人关联到房产
update_deal	推进交易至 Pipeline 的不同阶段，更新价格或备注

搜索档案（Suchprofile）

工具	描述
list_search_profiles	列出买家／租户的需求
create_search_profile	根据自然语言记录买家条件
update_search_profile	调整预算、城市、房间数和配套设施
delete_search_profile	删除搜索档案

项目（Projekte）

工具	描述
list_projects	列出开发项目及单元数量
get_project	获取项目详情，包括所有单元、媒体和文档

活动与事件（Aktivitaeten & Termine）

工具	描述
search_activities	查询联系人的房产或项目的完整活动时间线
list_events	日历事件——看房、会议，可按日期／状态筛选

电子邮件（E-Mails）

工具	描述
send_email	使用 Propstack 模板（片段）发送电子邮件
update_email	标记为已读／已归档、分类，并关联到 CRM 记录

文档（Dokumente）

工具	描述
list_documents	列出附加到房产、项目或联系人的文件
upload_document	上传文档（base64 数据 URI）

图片（Bilder）

工具	描述
list_property_images	按门户顺序列出房产图片和平面图（ID、标题、标记）
upload_image	向房产或项目上传图片（base64 数据 URI、门户可见性）
update_image	更改图片标题（包括 title_de / title_en）或门户可见性

关系（Beziehungen）

工具	描述
create_ownership	将联系人关联为房产所有者（Eigentuemer）
create_partnership	将联系人关联为买家、租户等（Kaeufer、Mieter）

查询（Konfiguration）

工具	描述
list_pipelines	获取包含阶段的交易 Pipeline（ID、名称、位置）
get_pipeline	获取单个 Pipeline 及阶段详情
list_tags	列出标签／分组（Merkmale）——按分组 ID 筛选联系人
create_tag	为联系人、房产或活动创建新标签
list_activity_types	列出用于 create_task 的备注／待办事项／事件模板
list_contact_statuses	列出用于搜索／分配的联系人状态
list_reservation_reasons	列出交易取消原因
list_custom_fields	查看自定义字段定义（名称、类型、选项）
list_users	列出所有经纪人／Agent 及其联系信息
list_teams	列出团队／部门及成员分配情况
list_locations	列出用于位置匹配的地理区域（Geolagen）

智能组合（Intelligente Workflows）

工具	描述
full_contact_360	完整的联系人档案 — 信息、搜索资料、交易、活动
property_performance_report	在售天数、咨询数、销售管道明细、活动摘要
pipeline_summary	各阶段的交易数、总金额、需要关注的停滞交易
smart_lead_intake	完整的线索工作流：去重、创建／更新、记录备注、交易、提醒
match_contacts_to_property	查找搜索资料与房产相匹配的买家
match_properties_to_contact	反向匹配：查找符合联系人搜索资料的房产

管理（Verwaltung）

工具	描述
list_webhooks	列出所有已配置的 webhook 订阅
create_webhook	订阅 CRM 事件（CLIENT_CREATED、PROPERTY_UPDATED 等）
delete_webhook	删除 webhook 订阅
get_contact_favorites	获取联系人收藏的房产

示例对话 / Beispiel-Konversationen

每日早间简报 / Morgen-Briefing

你： 我今天的日程是什么？

AI： 使用今天的日期范围调用 list_events — 你安排了 3 次看房……

你： 昨天以来有新线索吗？

AI： 使用 created_at_from=昨天调用 search_contacts — 有 5 个新联系人……

线索录入 / Leaderfassung

你： 我刚和 Maria Schmidt 通完电话，电话号码是 +49 157 1234 5678。她在柏林寻找一套 3 室公寓，预算为 30 万至 40 万，必须带阳台。她是在 ImmoScout 上找到我们的。

AI： 调用 smart_lead_intake — 已创建联系人（ID：4521），已记录通话备注，并设定明天 9:00 的跟进提醒。要我根据她的条件创建搜索资料吗？

房产匹配 / Objekt-Matching

你： 我们有一套新房源：位于 Charlottenburg 的 3 室公寓，售价 385,000 EUR。哪些人可能是买家？

AI： 调用 match_contacts_to_property — 找到 12 个匹配的搜索资料。排名前三的是：Herr Weber（得分 95%）、Frau Mueller（得分 88%）、Herr Kim（得分 85%）……

销售管道回顾

你： 我们的销售管道情况如何？有没有停滞的交易？

AI： 调用 pipeline_summary — 有 47 笔活跃交易，总价值为 12.3M EUR。有 5 笔交易超过 14 天未更新……

通话前简报 / Vor dem Anruf

你： 告诉我联系人 3847 的所有信息 — 我马上要打电话。

AI： 调用 full_contact_360 — Herr Weber，评级为 3 星，正在柏林／波茨坦寻找 3 室公寓，预算不超过 400k。有 2 笔活跃交易，最近一次活动是 3 天前……

数据保护（DSGVO）

英文摘要： 使用此 MCP 服务会将 Propstack CRM 中的个人数据发送到你连接的任意大模型。根据 GDPR 第 4 条第 7 款，你（Propstack 客户）是数据控制者（Verantwortlicher）——工具作者不托管或处理任何数据。以下德语部分涵盖控制者责任、大模型处理所需的法律依据、用于数据最小化的 fields 参数、关于 match_contacts_to_property 的自动化决策说明，以及审计日志记录。这些要点适用于任何处理客户数据的大模型工具；此处特别说明，是因为它们很容易被忽视。

责任

这是一个开源工具（Open Source）。每位用户都使用自己的 API 密钥连接自己的 Propstack 账户。服务器无状态，在各自用户的本地运行，且不存储任何数据。工具作者不会托管或处理任何数据。使用此工具的 Propstack 客户是 DSGVO 第 4 条第 7 款所指的数据控制者。

大模型处理

使用此工具时，个人数据（姓名、地址、联系方式，以及视工具而定的财务或交易数据）会传输到相应已连接的大模型（Claude、ChatGPT 等）的上下文窗口中。这构成 GDPR 第 4 条第 2 款所指的处理活动。数据控制者为此需要：

• 根据 GDPR 第 6 条确定法律依据，
• 在自己的隐私声明中作出相应说明（履行 GDPR 第 13/14 条规定的透明度义务，告知数据主体），
• 视情况与大模型提供商签订数据处理协议（AVV）。

这适用于所有处理客户数据的大模型驱动工具，并非此 MCP 服务所特有——但此处仍明确指出，以免这一点被忽略。

关于自动化决策的说明（match_contacts_to_property）

工具 match_contacts_to_property 会生成联系人与房产之间的匹配度评分（排名），供人工审核。该工具旨在提供决策支持，而非自主决策：经纪人会审核结果并手动采取行动。因此，这种使用方式不属于 GDPR 第 22 条的适用范围（该条仅涉及会产生法律效力或类似重大影响的完全自动化决策）。不过，数据控制者应确保该工具确实按此方式使用——也就是说，不应在未经人工审核的情况下，将其纳入完全自动化的联系流程。

数据最小化（fields 参数）

返回较大量个人数据的工具——search_contacts、search_properties、search_deals 和 full_contact_360——支持可选的 fields 参数。借助该参数，可以有针对性地仅获取所需字段（例如 ["first_name", "last_name", "email"]）。不指定 fields 时，行为保持不变（返回所有字段）。建议数据控制者使用 fields，只处理实现相应目的所必需的数据，以践行通过技术设计实现数据保护（GDPR 第 25 条）。

审计日志记录／访问控制

访问日志记录和访问控制由数据控制者负责，例如通过 Propstack 的权限管理（API 密钥权限）或在客户端或会话层面进行日志记录。由于该服务是无状态的，且在各个用户的本地运行，因此工具本身不包含此类日志记录功能。

开发

git clone <repo-url>
cd propstack-mcp-server
npm install
npm run build    # tsc → dist/
npm start        # requires PROPSTACK_API_KEY

项目结构

src/
  index.ts                 # Server entry point (stdio transport)
  propstack-client.ts      # HTTP client with auth, retry, error handling
  types/
    propstack.ts           # TypeScript interfaces for all API responses
  tools/
    helpers.ts             # Shared formatting utilities
    contacts.ts            # 7 contact tools
    properties.ts          # 5 property tools
    tasks.ts               # 3 task tools (polymorphic: note/todo/event/cancel)
    deals.ts               # 3 deal pipeline tools
    search-profiles.ts     # 4 search profile tools
    projects.ts            # 2 project tools
    activities.ts          # 2 activity/event tools
    emails.ts              # 2 email tools
    documents.ts           # 2 document tools
    relationships.ts       # 2 relationship tools (ownership/partnership)
    lookups.ts             # 8 lookup/config tools
    composites.ts          # 5 smart composite tools
    admin.ts               # 5 admin tools (webhooks, export, favorites)

许可证

MIT