FavCRM

FavCRM MCP

FavCRM Model Context Protocol 服务的安装片段、示例和文档。FavCRM 服务本身托管于 https://api.favcrm.io/mcp——此仓库用于客户端设置和社区示例。

通过 MCP 提供 231 个类型化工具，涵盖客户、预约、活动、忠诚度、发票、付款、WhatsApp / SMS / email。适用于任何支持 Streamable HTTP 传输的 Agent 客户端。

可通过 ?profile=<name> 或 X-FavCRM-MCP-Profile 选择专用工具配置：

• compact 提供精简的 search_tools + execute_tool 发现与路由接口，适用于大型 Agent 运行时。
• platform 仅提供超级管理员的客户工作区和公司设置操作，无需启用中的商户公司，且绝不提供原始 SQL。
• full 仍是客户端和扫描器的默认配置。

平台运营者可以从专用的 Cursor 或 Claude Desktop 配置开始。普通商户 API 密钥无法访问平台工具。

🤖 AI Agent 技能

正在使用 AI Agent 对接 FavCRM 无头后端？安装我们的官方技能，让 AI 了解最佳实践、标准操作流程和 MCP 工具形式：

# Example: Install the Booking Operator skill
npx skills add https://github.com/favcrm/mcp/tree/main/skills/favcrm-booking-operator

# Or install all skills at once
npx skills add favcrm/mcp

完整的可用 Agent 技能列表，请参阅 skills/ 目录。

公开的 Agent 技能位于 skills/：这些可移植的工作流包适用于 Agent 注册、团队入门、渠道设置、预约管理、客户生命周期、通信审批、账单与商务、内容、销售运营、知识培训和报告。Agent 和营销人员都可以阅读其源代码，而 FavCRM 运行时则通过平台技能注册表安装经过审核的版本。

客户端	状态	设置
Vercel v0	✅ 已上线	从市场安装 — 自动配置工作区并注入环境变量
Cursor	✅ 已上线	mcp.json 片段
Smithery	✅ 已上线	smithery mcp add favcrm/favcrm
Claude Desktop / Connector	🚧 待推出	OAuth 提供方（第 3 阶段，约 3 周）
ChatGPT Apps Directory	🚧 待推出	列表正在审核中
Windsurf / Continue.dev / Zed	✅ 可用	与 Cursor 相同的 mcp.json 结构

---

获取密钥

有两种方式：

选项 A — 让 Agent 帮你注册（无需填写表单或点击门户）

先使用占位环境变量将 FavCRM 连接到客户端（请参阅下方的 Cursor 部分）。然后让 Agent：

“帮我注册 FavCRM。香港有一家名为 Stretch + Breathe 的瑜伽工作室。”

Agent 将：

1. 调用 register_organisation_request——服务会向你发送一封包含 6 位数代码的邮件
2. 将代码粘贴回聊天中
3. Agent 调用 register_organisation_verify——服务会返回一个新的 fav_mcp_* 密钥
4. Agent 保存密钥并立即开始工作

请参阅 skills/favcrm-agentic-registration，了解可移植的 SKILL.md 工作流。

后台流程：10 分钟有效的一次性密码（OTP）、真实的邮箱所有权验证，以及按 IP 限流（每小时 3 次，每天 20 次）。无钓鱼攻击入口，无虚假演示。

选项 B — 通过传统方式注册

favcrm.io/signup → 门户 → Settings → MCP Keys → 复制 fav_mcp_* 值。

现有 FavCRM 商户：位置相同，使用 MCP 无需升级套餐。

**免费套餐（两种方式均适用）：**100 位客户、每月 200 次预约、每月 1k 次 MCP 调用，以及 30 天更高限额试用期。

从命令行引导

favcrm CLI 也可以运行零状态流程：

favcrm signup request --email [email protected] --organisation-name "Ada Studio"
favcrm signup verify --request-id <request-id> --code <code>
favcrm doctor
favcrm team invite create --email [email protected] --role staff
favcrm whatsapp status
favcrm whatsapp connect --mode cloud-api

团队受邀者无需现有 API 密钥即可接受邀请：

favcrm team invite accept-request --token <invite-token>
favcrm team invite accept-verify --token <invite-token> --code <code>

---

Cursor

已验证方案，见 cursor.com/docs/mcp。

~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）：

{
  "mcpServers": {
    "favcrm": {
      "url": "https://api.favcrm.io/mcp",
      "headers": {
        "Authorization": "Bearer ${env:FAVCRM_API_KEY}"
      }
    }
  }
}

然后导出密钥——在 Cursor 进程读取环境变量的任何位置均可：

# shell rc
echo 'export FAVCRM_API_KEY=fav_mcp_...' >> ~/.zshrc

# or per-project (direnv)
echo 'export FAVCRM_API_KEY=fav_mcp_...' >> .envrc

重启 Cursor → Settings → MCP → favcrm 连接 → 231 个工具出现在聊天中。

为什么使用 ${env:VAR}，而不是直接写入？Cursor 会在请求时插入环境变量，因此密钥不会进入你的代码仓库或共享配置。

---

Smithery

Smithery 上的 favcrm.io — 通过 CLI 安装：

npm i -g @smithery/cli
smithery login
smithery mcp add favcrm/favcrm

若要安装到特定项目，smithery mcp add favcrm/favcrm --client cursor 会写入正确的 mcp.json 配置块。

---

Claude Desktop

🚧 基于 OAuth 的连接器计划在第 3 阶段推出。上线后：

1. claude.com → Connectors → Add custom connector
2. URL：https://api.favcrm.io/mcp
3. 通过 OAuth 授权 → 工作区选择器 → 工具列表

在此之前，高级用户可以按照与 Cursor 相同的 Bearer 标头方案，将 FavCRM 接入 Claude Desktop 的 claude_desktop_config.json（仅限社区方案；目前不在 Anthropic 的连接器目录中）。

---

ChatGPT

🚧 Apps Directory 中的条目正在审核。获批后：

1. ChatGPT → Tools 菜单 → Apps → 搜索 "FavCRM"
2. 添加 → OAuth 握手 → 工作区选择器
3. 26 个精选工具出现在聊天中（以读取为主，并支持安全写入；破坏性操作须经确认）

---

测试

配置生效后，ChatGPT/Cursor/Claude 会自动列出工具。若要通过命令行进行快速测试：

# Discovery (no auth needed — public-scan endpoint)
curl https://api.favcrm.io/.well-known/mcp/server-card.json | jq '.tools | length'
# → 231

# Auth + initialize
curl -s https://api.favcrm.io/mcp \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $FAVCRM_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' \
  | jq

# Call a read-only tool
curl -s https://api.favcrm.io/mcp \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $FAVCRM_API_KEY" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_membership_tiers","arguments":{}}}' \
  | jq

更多内容请参见 examples/。

---

工具概览

231 个工具，分布于 28 个作用域。每个工具都带有注释：

• title — 易于理解的标签
• readOnlyHint — 对 list_* / get_* / search_* 等操作为 true
• destructiveHint — 对 delete_* / cancel_* / void_* / refund_* 等操作为 true
• openWorldHint — 对会调用外部服务（WhatsApp、Stripe、电子邮件）的工具为 true
• idempotentHint — 对 set_* / update_* / upsert_* 操作和只读操作为 true

客户端可以利用这些信息限制破坏性调用或估算成本。完整目录 https://api.favcrm.io/.well-known/mcp/server-card.json 是权威信息来源；此处的列表仅为摘要。

使用精简工具集或受上下文限制的 Agent 应使用 search_tools 发现操作，然后使用 execute_tool 运行所选工具。猜测行为或参数结构之前，请使用 query_favcrm_platform 查询平台文档。对于商家专属信息、政策、定价说明、常见问题或品牌指南，请使用 query_company_knowledge；它返回带有源文档 ID 的片段，而非完整文档。

作用域	工具示例	只读	写入
contacts	search_members、get_member_profile、create_account、attach_tags	5	6
customer_segments	list_segments、preview_segment_count、set_segment_members	4	4
custom_fields	list_custom_fields、create_custom_field、set_custom_field_values	3	4
bookings	list_services、get_available_slots、create_booking	12	15
events	list_event_registrations、get_event_campaign_exclusions	2	0
membership	list_tiers、enrol_membership、earn_loyalty_points	4	3
shop	list_products、get_order、create_order	8	6
invoices	list_invoices、mark_invoice_paid	4	4
campaigns	list_campaigns、send_campaign（受限）	5	3
blog	list_posts、publish_post	14	13

超级管理员平台工具使用独立的作用域系列：

作用域	功能
platform:customer_setup	搜索／创建客户工作区并配置公司设置
platform:catalog	在完整配置中管理全局套餐、模块和 AI 媒体目录
platform:sql_read	在完整配置中使用紧急访问权限执行 SELECT/EXPLAIN
platform:sql_write	在完整配置中使用紧急访问权限执行 DML 操作
platform:*	所有平台功能；仅供受控的内部操作人员使用

SQL 作用域必须显式指定；即使使用 platform:*，platform 配置中仍无法使用 SQL 工具。

---

Agent 问题报告

如果缺少原生 MCP 操作路径、工具架构不清楚、工具意外失败，或不得不改用 REST/SDK 操作，Agent 应调用 report_agent_issue。请提供预期行为、实际行为、尝试过的步骤、相关工具调用／日志、AI 分析以及需要澄清的问题。FavCRM 会将这些报告转交平台支持队列进行分诊。

示例：

favcrm tool call report_agent_issue '{"title":"Missing account creation MCP tool","severity":"high","area":"mcp_tool_missing","expectedBehavior":"Agent can create an account via MCP only.","actualBehavior":"Agent had to use SDK fallback.","stepsTried":["Listed tools","Tried create_contact"],"aiAnalysis":"Account creation exists in backend services but was not exposed in MCP."}'

套餐操作

Agent 可以直接在 MCP 中检查套餐访问权限并进行预检：

favcrm tool call get_plan_status '{}'
favcrm tool call check_plan_operation '{"toolName":"create_account"}'
favcrm tool call list_plan_options '{}'
favcrm tool call create_plan_upgrade_link '{"planCode":"favcrm-lite","billingCycle":"monthly","confirm":true}'

对于可能触发模块、作用域、订阅或配额限制的写入操作，请先使用 check_plan_operation。如果结果包含 upgradeAction，请向用户展示返回的操作。只有通过 create_plan_upgrade_link 并设置 confirm=true，才会创建 Stripe 链接。

---

身份验证模式

令牌类型	有效期	用途
fav_mcp_* API key	长期有效，可撤销	Cursor、Windsurf、Zed、Continue.dev、脚本
fav_v0_* partner token	按 Vercel 项目限定范围	仅用于 v0 / Vercel 安装
OAuth bearer（15 分钟 JWT + 30 天 refresh）	短期有效	Claude Connectors（第 3 阶段）、ChatGPT Apps
OTP-issued JWT（60 分钟）	短期有效	交互式用户（通过商家门户兑换）

无论底层权限范围如何，市场平台令牌（fav_v0_*、由 OAuth 签发的令牌）都会被硬性禁止用于超级管理员工具（原始 SQL、套餐管理）——这是在请求层进行的纵深防御，而不只是基于每个令牌的 RBAC。

---

定价

套餐	价格	限制
免费版	$0	100 位客户 · 每月 200 个预约 · 每月 1k 次 MCP 调用
Lite	$19 / 月	1 个席位 · 邮件沟通 · 通过你的 Agent 使用自带 AI
Starter	$49 / 月	3 个席位 · 1M 个 AI 积分 · WhatsApp + SMS · 会议记录
Enterprise	定制	无限席位 · 多地点 · 定制路由

完整价格表：favcrm.io/pricing。

---

问题反馈 / 贡献

• 工具行为或 MCP 传输方面的错误：在此提交问题。
• 新客户端（Cline、Replit Agent、Roo 等）的示例：欢迎通过 PR 提交至 examples/。
• Agent 工作流技能：欢迎通过 PR 提交至 skills/。
• 贡献指南：CONTRIBUTING.md。
• 安全问题报告：请遵循 SECURITY.md；请勿公开提交漏洞问题。
• 服务错误 / 新工具请求 / 商务咨询：[email protected]。

---

链接

• favcrm.io — 落地页
• favcrm.io/integrations/vercel · /cursor · /chatgpt — 各平台安装指南
• favcrm.io/developers — 完整开发者文档
• favcrm.io/pricing — 定价表
• favcrm.io/privacy-policy · /terms-of-use

品牌素材

可用于市场平台的 1:1 图标，带背景底板，位于 assets/ 中：

文件	用途
assets/icon.png	512×512 PNG — Cursor / Smithery / mcp.so 列表
assets/favcrm-icon-256-dark.svg	1:1 SVG，墨色底板、浅色图形 — 适用于大多数市场平台
assets/favcrm-icon-256-light.svg	1:1 SVG，画布色底板、墨色图形 — 适用于浅色主题界面
assets/favcrm-icon-256-dark.png	256×256 PNG 备用版本

所有图标均为 1:1 长宽比，带圆角方形底板（在 256 单位网格上，圆角半径为 48px），中央为「fav.」字标图形。

许可证

本仓库（文档 + 示例）采用 MIT 许可证，详见 LICENSE。托管的 MCP 服务是专有的 FavCRM SaaS；安装需要 FavCRM 账户。