Livespace CRM MCP Server

Livespace CRM MCP 服务

面向 Livespace CRM 的非官方 MCP 服务。它提供 11 个按意图设计的工具，而非照搬原始 API，并采用 MCP 规范 2026-07-28 中的无状态 Streamable HTTP 传输方式。

0.1.2 版本已发布至 npm、官方 MCP Registry 以及 GitHub Release。

v1 实现已在此仓库中完成。它包含 6 个读取工具和 5 个可选写入工具，默认只读，API 访问范围受限，错误信息经过清理，并采用优先征询的确认流程。评估时请使用 Livespace 测试账户。

为什么采用这种设计？

Livespace 的 RPC API 大约有 80 个方法，但不支持排序、聚合，也没有直接设置交易阶段的操作。此服务将这些底层调用整合为 MCP 客户端可安全使用的任务：

• 使用 ID 前先进行发现；
• 限定范围的搜索、记录读取和分析；
• 写入前提供批量预览；
• 提供逐项处理结果和写入后检查；
• 明确处理 Livespace 特有的阶段变更和通知。

工具

工具	模式	用途和限制
health	读取	检查服务；checkLivespace: true 还会调用一次轻量级 Livespace API。
crm_metadata	读取	返回 9 个字典类别，包括流程、用户、群组、来源、任务字典、产品和当前用户。可选的 userQuery 会在 500 行上限内按姓名或电子邮件筛选用户。
search_crm	读取	搜索个人、公司或交易，即使是轻量级结果也会包含记录链接。交易搜索排序时会使用一个包含 200 条记录的排序窗口，并报告截断情况。
get_records	读取	读取一种记录，最多读取 25 个 ID；个人、公司或交易最多读取 5 条记录的动态。
get_activity	读取	每次调用读取一条记录的动态、一个范围受限的 CRM 动态流区间，或有限页数的任务。
analyze	读取	在有限窗口内执行一个指定的聚合，并报告其来源窗口是否被截断。
create_records	写入	创建个人、公司、交易或任务。每次调用最多处理 10 项，默认按精确匹配去重联系人。
update_records	写入	更新个人、公司、交易或任务。每次调用最多处理 10 项。
log_activities	写入	添加公开备注或电话记录。每次调用最多添加 15 条备注或电话记录。
move_deals_to_stage	写入	通过应用最小流程步骤差异来移动交易。每次调用最多处理 10 项；向后移动需要明确的允许列表。
notify_user	写入	发送一条应用内通知；每 10 分钟最多 5 条，且每位接收者每分钟最多 1 条。

由于 Livespace 没有“设置阶段”调用，move_deals_to_stage 会通过勾选和取消勾选流程步骤来移动交易。交易所处阶段以勾选到最远处的步骤为准。因此，向后移动会取消勾选已完成的步骤，并可能改变这些复选框所代表的历史含义。

notify_user 会验证接收者，并可添加指向记录的深层链接。Livespace 不提供通知读取确认，因此该工具只会将成功请求报告为已发送，不会声称通知已送达。

要求

• 具有 API 访问权限的 Livespace 套餐，目前需要 Automation 或更高版本。
• 一个 Livespace API 密钥和密钥密码，可在 Account settings -> API -> Users 中获取。请使用仅具备此 MCP 所需权限的专用 Livespace API 用户。每项 API 操作都会继承该用户的权限。
• Bun 1.3.14 或更高版本（bun.sh）。当前服务使用 Bun.serve，没有 Node.js 或 Cloudflare Workers 适配器。

v1 部署模式为单用户：一组 Livespace 凭据，以及一个可选的 MCP bearer token，用于保护服务。它不支持 OAuth，也不支持多用户凭据路由。

从 npm 安装并运行

此软件包通过 npm 公共注册表分发，但运行时使用 Bun。运行它不需要 Node.js 或 npm CLI。

首次评估时，请在 Git 仓库之外创建一个私有工作目录。在其中添加一个 .env 文件，并填入你自己的 Livespace 凭据：

LIVESPACE_SUBDOMAIN=
LIVESPACE_API_KEY=
LIVESPACE_API_SECRET=

填入三个空值并保护该文件，然后启动已发布的软件包：

chmod 600 .env
bunx livespace-crm-mcp

默认端点为 http://127.0.0.1:3020/mcp。在 MCP 客户端连接期间，请让进程保持运行。请先以只读模式启动并调用 health，然后在任何需要用户、流程、阶段、组或字典 ID 的操作之前使用 crm_metadata。

bunx 会从 npm 下载软件包并在本地缓存。要固定到此版本，请运行 bunx [email protected]。

连接 MCP 客户端

配置支持 Streamable HTTP 的客户端，并使用以下服务 URL：

{
  "url": "http://127.0.0.1:3020/mcp"
}

不同客户端的确切配置字段各不相同。请设置 MCP_AUTH_TOKEN，并将客户端配置为发送 Authorization: Bearer <your-token>，即使是在环回地址上也是如此。启用写入工具时，必须进行身份验证。

此软件包提供 Streamable HTTP，而非 stdio。一些 MCP 客户端可以连接本地 URL，但无法代你启动 bunx，因此请在单独的终端中运行该命令。目前尚不支持仅接受 stdio 的客户端。每个 HTTP 请求必须包含一条 JSON-RPC 消息；在分发前会拒绝顶层批量数组。

读取结果

记录数据放在 structuredContent 中，并附有简短的文本摘要。请确认你的宿主会将两个通道都传递给模型。空的 search_crm 和 get_activity 页面会在两个通道中包含相同的 hint；在判定没有匹配记录之前，请先跟进返回的游标。空的 crm_metadata 用户搜索也会在两个通道中包含提示。请参阅宿主兼容性检查，了解经过测试的版本、确认限制，以及无需访问 CRM 即可运行的合成测试数据。

使用 crm_metadata 搭配 userQuery，按姓名或电子邮件的一部分查找用户。例如，{"userQuery":"[email protected]"} 只会返回用户部分。去除首尾空格后，查询必须包含 2 至 100 个字符。匹配时不区分大小写，但会保留重音符号；不会搜索团队名称。如果提供 sections，其中必须包含 users；其他请求的部分仍不会经过筛选。省略查询时，将保留通常的部分选择行为。

工具会按字典顺序返回所有匹配用户，最多 500 位。选择负责人或写入对象之前，请先处理多个匹配项。totalItems 统计缓存字典中符合条件的用户数量，不受此上限影响。尤其是在结果中找不到某位用户时，请检查 asOf、ageMs 和 stale。

短语搜索链接会根据 API ID 在本地生成，不会单独检查每个目标地址。ID 不可用时，url 为空。记录读取和筛选搜索会保留 Livespace 提供的 URL；对于人员、公司和交易，即使 detail: "minimal" 也是如此。该 URL 也可能为空。任务没有记录 URL。

detail 排除的字段不会返回。返回值为空或为 null，表示响应未提供该值；这并不能证明 CRM 字段为空或存在访问限制。对于交易金额和概率，请区分数值零与 null。仅凭预算为零，无法判断这是否是有人有意设置的。某些计数器和标志会将缺失数据规范化为零或 false，因此这些默认值不能证明曾明确存储过该值。

交易的 value 取决于账户填写的字段。使用预算明细的账户会将明细合计保存在 value 中。其他账户会在每笔交易中报告 value: 0，并将界面上显示的金额保存在 value_final 中。如果 value_final 非零，服务会返回该值；否则返回 value，因此 search_crm、get_records 和 analyze 在这两类账户中显示的金额都与界面一致。

在 detail: "full" 时，交易还会包含 checkedSteps（已标记为完成的流程步骤，附有阶段和步骤的 ID 与名称），以及赢单、输单和过期原因的名称与备注。重新打开的交易可能保留先前的输单原因，因此请先检查 status。search_crm 筛选条件支持为人员、公司和交易指定 createdFrom 和 createdTo，并为交易指定 modifiedFrom；这些日期均采用包含边界的 YYYY-MM-DD 格式。Livespace 无法读取日期时会忽略该日期并返回所有记录，因此服务会在调用 Livespace 前拒绝无效日期。交易的 status 筛选条件接受 open（默认值）、won、lost、outdated 或 all。

所有工具都会拒绝不受支持的输入参数。客户端报告输入验证错误时，请修正参数。

配置

变量	用途
LIVESPACE_SUBDOMAIN	账户子域名，不包含协议或 .livespace.io。
LIVESPACE_API_KEY / LIVESPACE_API_SECRET	一位 Livespace 用户的凭据。
MCP_PORT	服务端口。默认值：3020。
MCP_BIND_HOST	绑定地址。默认值：127.0.0.1。
MCP_AUTH_TOKEN	至少 32 字节的随机 Bearer 令牌。写操作以及绑定到非环回地址时必需；建议所有服务都设置。
LIVESPACE_MCP_ENABLE_WRITES	设为 true 以开放写入工具。默认值：false。
LIVESPACE_MCP_READ_ONLY	紧急终止开关。设为 true 后，即使已启用上述设置，也会移除并阻止写入工具。
MCP_REQUEST_STATE_KEY	用于签署写入确认的独立随机密钥，至少 32 字节。启用写操作时必需。
MCP_ALLOW_UNBOUND_WRITE_CONFIRMATION	不支持表单征询的客户端所用的不安全兼容模式。默认值：false。
MCP_ALLOWED_HOSTS	用于防范 DNS 重绑定的 Host 标头允许列表。绑定到非环回地址时必需。
MCP_ALLOWED_ORIGIN_HOSTNAMES	可选的额外浏览器来源主机名。绑定到非环回地址时，默认采用 MCP_ALLOWED_HOSTS。
MCP_RATE_LIMIT_PER_MINUTE / MCP_RATE_LIMIT_BURST	每个主体的请求速率限制。默认值：每分钟 120 次，突发 30 次。
MCP_MAX_CONCURRENT_REQUESTS / MCP_MAX_QUEUED_REQUESTS	接纳限制。默认值：并发处理中 8 个，排队 16 个。
MCP_REQUEST_INGRESS_TIMEOUT_MS	接纳排队加请求体上传的绝对时限，不包括工具执行。默认值：10000；最大值：60000。
MCP_REQUEST_EXECUTION_TIMEOUT_MS	上传完成后工具执行的绝对时限。默认值：90000；最大值：180000（0.1.2 之前为 300000；现在超过此值会阻止启动）。HTTP 空闲超时会遵循这两个时限。

如果没有设置 MCP_AUTH_TOKEN 和 MCP_ALLOWED_HOSTS，服务将拒绝绑定到非环回地址。启用写操作时，如果没有同时设置 MCP_AUTH_TOKEN 和 MCP_REQUEST_STATE_KEY，服务也会拒绝启用。配置 MCP_AUTH_TOKEN 后，每个 /mcp 请求都必须携带该 Bearer 令牌，包括环回地址上的请求。Host 和 Origin 检查会在 MCP 处理程序运行前执行。

运行两次 openssl rand -hex 32，分别生成独立的 MCP_AUTH_TOKEN 和 MCP_REQUEST_STATE_KEY。不要重复使用 Livespace 凭据。

Bun 进程不会终止 TLS。在每个通过网络暴露的部署前，都应放置支持 TLS 的反向代理。服务会从环境变量中读取凭据，通常通过 Bun 加载 .env；.env 静态存储时的保护由运营者负责。切勿将其提交到版本库。冒烟测试脚本也可以从 macOS 钥匙串读取沙盒凭据。

写入安全

正常流程优先请求确认：

1. dryRun: true 会生成计划，不会写入或请求批准。
2. 对于支持表单式确认的客户端，不带 dryRun: true 的调用会请求人工批准计划后再执行。confirm: true 参数无法绕过此提示。
3. 确认交互使用签名的 requestState，有效期为五分钟，并会在收到接受或拒绝的响应后失效。如果存在经过身份验证的主体，该状态会绑定到该主体，同时也会绑定到工具、参数和预览内容。
4. 如果相关记录在批准前发生变化，工具会返回 recordsChanged: true，不执行任何写入，并提供一份新计划。

默认情况下，不支持表单式确认的客户端无法执行写入。这些客户端可以预览，但 confirm: true 会被拒绝。为兼容旧行为，运维人员可以设置 MCP_ALLOW_UNBOUND_WRITE_CONFIRMATION=true。在此模式下，confirm: true 会直接执行，且没有签名证明表明人工查看过预览。

结果会区分以下情况：

• verification: verified 表示服务在写入后重新读取了可比较的字段。
• 即使写入成功，如果后续读取失败、发送的字段没有独立比对值，或上游 API 不支持回读，也可能报告 verification: unavailable。检查该条目的错误，并在可能的情况下重新读取记录；不要重试写入。
• unknown_outcome 表示请求可能已生效，也可能未生效。切勿盲目重试。
• not_attempted 表示未发送该条目，通常是因为时间预算已耗尽，或较早的条目触发了上游速率限制。之后可以提交这些未发送的条目；对于触发速率限制的条目，请遵循错误提示。

通知成功状态会报告为已调度，绝不会报告为已送达。如果送达情况很重要，请通过其他渠道确认，而不是重复发送通知。

安全与隐私

CRM 名称、备注、导入的电子邮件、任务文本和墙面条目都属于不可信数据。服务端绝不会将其作为指令执行，但其内容仍可能影响 MCP 宿主和模型。除非客户端提供人工确认流程，否则请保持写入功能禁用。只获取任务所需的记录和详细信息。

MCP 宿主、模型提供商或本地客户端日志可能会保留工具响应。请选择存储、训练和保留政策符合所处理 CRM 数据要求的宿主。此服务不会在磁盘上存储 CRM 记录，也不会发送遥测数据，但无法控制宿主收到结果后的行为。

请使用专用的 Livespace API 用户，而非管理员的密钥。仅授予该用户所需的最小记录权限和写入权限。在将 MCP 接入业务数据之前，先使用单独的测试账户进行评估。

如果使用反向代理，请终止 TLS、禁用缓存，并且不要记录 MCP 请求或响应正文。服务会设置 Cache-Control: no-store 和 Vary: Authorization，但代理策略必须保留这些保护措施。

事件响应

如果 Livespace 密钥、Bearer 令牌或确认密钥可能已泄露：

1. 停止 MCP 服务。
2. 立即撤销 Livespace API 密钥，并为专用 API 用户签发替代密钥。
3. 生成新的、相互独立的 MCP_AUTH_TOKEN 和 MCP_REQUEST_STATE_KEY 值。
4. 重启服务并更新 MCP 客户端的 Bearer 标头。
5. 检查 Livespace 的记录和活动历史，查找意外写入。不要重试之前返回 unknown_outcome 的任何操作。

v1 限制

• 不支持删除或合并操作。
• v1 不支持写入标签或自定义字段。Livespace 通过 tag_add 和 tag_remove 记录标签变更，并通过 dataset 记录自定义字段。标签写入 仍需使用这些确切键进行沙盒探测。只有沙盒中包含涵盖受支持类型的字段（包括选择字段的答案 ID）后， 才能验证自定义字段写入。
• 在此创建的任务无法关联记录。Livespace 的 Todo/addTodo 文档 说明可通过 todo.objects 建立关联，但我们的沙盒探测返回成功，并回显了提交的关联，而重新读取时 返回 objects: []。未保留确切的原始探测载荷，因此结果尚无定论。在受控探测确认关联 持久保存之前，服务不会在任务写入中包含 objects。Livespace 返回的现有关联仍会作为 linkedRecords 提供。
• 已记录的备注和通话无法编辑或删除。
• 交易更新仅涵盖名称和状态（open、won 或 lost）；阶段变更使用 move_deals_to_stage。create_records 可在创建交易时设置预算明细，但 update_records 不会编辑现有预算，因为尚未验证追加还是替换的行为。
• stage_conversion 是某个时间点的估算值，因为 Livespace 不提供阶段历史记录。
• 读取和分析均使用有界时间窗口。请先检查截断字段，再判断结果是否完整。
• 缺失值和多种货币混用可能导致货币总和为 null；结果会说明原因。
• API ID 与 Livespace 界面中显示的 ID 不同。请使用 crm_metadata、search_crm 或其他工具返回的 ID，切勿猜测。

开发

如需使用源代码而非已发布的软件包进行开发：

git clone https://github.com/proAutomator/livespace-crm-mcp.git
cd livespace-crm-mcp
bun install
cp .env.example .env
bun run dev

仓库命令如下：

bun test                 # complete offline suite
bun run test:security    # focused security contract from docs/security.md
bun run typecheck
bun run smoke            # live test-account check via .env or macOS Keychain
bun run dev

bun run smoke 和启用 checkLivespace: true 的 health 会发起真实 API 调用。 请仅使用 Livespace 测试账户，切勿使用生产 CRM。

具有约束力的威胁模型和回归映射见 docs/security.md。 请按照 SECURITY.md 中的说明私下报告漏洞。

免责声明

社区项目。与 Livespace S.A. 无关联，未获其背书或支持。“Livespace”是其所有者的商标，此处仅用于说明兼容性。通过 Livespace API 执行的操作使用您的 API 密钥，并且根据 Livespace 服务条款，责任由您承担。

致谢

此服务采用了 Adam Gospodarczyk（overment）的 MCP 服务中的模式，尤其是 iceener/streamable-mcp-server-template （MIT）：小巧、按意图设计的工具界面、操作说明、以批量操作为优先并提供逐项结果的写入方式，以及附带恢复提示的错误信息。感谢 Adam。

作者

由 Kuba Masztalski 构建

• LinkedIn：linkedin.com/in/kuba-masztalski
• X：@proAutomator

错误和功能请求： GitHub Issues。 安全问题报告：请参阅 SECURITY.md。

许可证

MIT