Fresha by Cotlet

Fresha API 和 MCP 服务，可自托管

一个 Fresha API 和 Fresha MCP 服务，使用 Python 在你自己的电脑上，通过你自己的 Google Chrome 会话运行。包含我们在 Cotlet 投入生产环境的全部 17 个 Fresha 工具：预约、空闲时段、预订、改期和取消、屏蔽时段、客户和客户备注、服务和团队、销售汇总和销售列表报告，以及评价和回复。

Fresha 没有公开 API，也没有官方 MCP 服务。它唯一的数据连接方式是付费的 Data Connector 附加组件，它会将你的数据复制到 Snowflake 数据库，但无法预订任何内容。本仓库提供：

• 面向 Claude Code、Claude Desktop、Cursor、Codex 及任何 MCP 客户端的 MCP 服务，支持 stdio 或 HTTP。设置
• 位于 http://127.0.0.1:8787/api/v1/fresha 的 REST API，OpenAPI 文档位于 /docs。设置
• Python：call("list_appointments", {"from": "2026-10-27", "to": "2026-10-27"})，以及 examples/ 中的 9 个现成脚本。

本项目面向希望自行运行的技术人员，仅供非商业用途（许可证）。如果你希望它在服务器上全天候运行，在 Fresha 更改管理面板后仍能正常工作，供团队或企业使用，请使用 cotlet.dev 上托管的版本。

git clone https://github.com/cotletdev/fresha-api-mcp-server.git && cd fresha-api-mcp-server
python3 -m venv .venv && . .venv/bin/activate && pip install -e .
fresha-mcp connect                                 # reads your Fresha session from Chrome
fresha-mcp call list_services
claude mcp add fresha -- "$PWD/.venv/bin/fresha-mcp" mcp

目录

• 工作原理
• 要求
• 安装
• 连接你的 Chrome
• MCP 服务
• REST API
• Python 和示例脚本
• 全部 17 个工具
• 配置
• 安全性和你的 Fresha 账户
• 错误
• 自托管或托管版
• 常见问题
• 许可证

工作原理

AI agent (MCP) / script (REST, Python) ──▶ fresha-mcp on your computer ──your cookies──▶ *.fresha.com
                                                  ▲
                         fresha-mcp connect ──────┘ reads them once from your Chrome (DevTools Protocol)

1. 像往常一样，在你自己的 Chrome 中通过 partners.fresha.com 登录 Fresha for business：先输入电子邮件验证码，再输入短信验证码。勾选 信任此设备。
2. fresha-mcp connect 通过 Chrome DevTools Protocol 连接到该 Chrome，读取 fresha.com Cookie，并将其保存到 ~/.config/fresha-api-mcp/session.json，仅你的用户可读取。它不会查看或存储你的密码或验证码。
3. 每次工具调用都会携带这些 Cookie，向 Fresha 商家面板本身调用的 API 发起请求（partners-api、partners-api-gateway GraphQL、customers-api、reports.fresha.com，以及其他几个 *.fresha.com 主机），请求通过 curl_cffi 发送，该库会复制 Chrome 的 TLS 指纹。不会运行无头浏览器。

会话保存在一个 Cookie fresha_partners_session 中。Fresha 会保留该 Cookie 25 天，并在你使用管理面板或工具期间续期。当 Fresha 将你登出时，只要 Chrome 已开启远程调试，服务就会再次从 Chrome 读取 Cookie。

要求

• Python 3.11 或更高版本。
• Google Chrome 144 或更高版本，并已登录 partners.fresha.com。任何 Chrome 或 Chromium 浏览器均可使用，只需配置调试端口。
• macOS、Linux 或 Windows。
• Fresha for business 账户。我们使用工作区所有者账户进行构建和测试。团队成员登录后只能看到 Fresha 向该成员展示的内容，且两个销售工具需要相应的报告权限。

安装

git clone https://github.com/cotletdev/fresha-api-mcp-server.git
cd fresha-api-mcp-server
python3 -m venv .venv
. .venv/bin/activate              # Windows: .venv\Scripts\activate
pip install -e .
fresha-mcp --version

使用 uv：uv venv && uv pip install -e .，然后运行 uv run fresha-mcp ...。

要使用 AI Agent（Claude Code、Codex、Cursor）进行设置？在此文件夹中打开项目，并让它设置代码库：AGENTS.md 列出了所有步骤；只有在 Chrome 中操作的步骤需要你完成。

更新方式：git pull && pip install -e .。托管版 Fresha 工具的每项变更都会同步到此代码库。

连接 Chrome

选项 A：日常使用的 Chrome（推荐）

1. 在 Chrome 中打开 chrome://inspect/#remote-debugging，并开启远程调试。Chrome 随后会接受来自此计算机上程序的 DevTools 连接，并在每次连接前征求你的许可。

2. 确认你已登录 partners.fresha.com。

3. 运行：

   fresha-mcp connect
   

4. Chrome 会询问是否允许连接。点击允许。

Saved 24 Fresha cookies to /Users/you/.config/fresha-api-mcp/session.json
Signed in to Fresha as Daniel Hughes ([email protected])

之后可以再次关闭远程调试。如果你希望 Fresha 将你登出后，服务能自行获取新的会话，则保持开启。

connect 会在 Chrome 默认配置文件夹中查找 Chrome 的 DevToolsActivePort 文件。对于 Chrome Beta、Canary 或自定义配置文件夹，请传入 --profile-dir "<folder>"。

选项 B：使用调试端口启动 Chrome

Chrome 不会在默认配置文件上开放调试端口，因此请另外启动一个 Chrome 实例，在其中登录 Fresha 一次，然后连接该实例：

# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-fresha"
# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-fresha"
# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="%USERPROFILE%\.chrome-fresha"

fresha-mcp connect --cdp http://127.0.0.1:9222

--cdp 也接受 ws:// DevTools URL，例如通过 SSH 隧道连接到另一台计算机上的 Chrome。

选项 C：手动粘贴 Cookie

适用于没有 Chrome 的服务端：在 Chrome 中打开 partners.fresha.com 的 DevTools，选择 **Application > Cookies > https://partners.fresha.com**，复制 fresha_partners_session 的值，然后：

fresha-mcp connect --token          # paste it, input is hidden
# or, without a session file:
export FRESHA_AUTH_TOKEN=...

粘贴的 Cookie 不会再次从 Chrome 中读取。Fresha 将你登出后，请粘贴新的 Cookie。

随时检查会话：

fresha-mcp status

MCP 服务

MCP 服务会列出所有工具及其输入架构、面向 Agent 编写的说明和提示。读取工具标记为只读；能够联系客户的工具（预约、改期、取消、回复评价）也会标记出来，以便客户端在运行这些工具前征求你的许可。

Claude Code

claude mcp add fresha -- /path/to/fresha-api-mcp-server/.venv/bin/fresha-mcp mcp
# read only:
claude mcp add fresha -- /path/to/fresha-api-mcp-server/.venv/bin/fresha-mcp mcp --read-only

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "fresha": {
      "command": "/path/to/fresha-api-mcp-server/.venv/bin/fresha-mcp",
      "args": ["mcp"]
    }
  }
}

Cursor

~/.cursor/mcp.json，内容与 Claude Desktop 相同。可直接使用的副本位于 mcp.json。

Codex

~/.codex/config.toml：

[mcp_servers.fresha]
command = "/path/to/fresha-api-mcp-server/.venv/bin/fresha-mcp"
args = ["mcp"]

通过 HTTP

fresha-mcp serve 还会通过可流式传输的 HTTP，在 http://127.0.0.1:8787/mcp 提供 MCP 服务，供需要 URL 的客户端使用：

fresha-mcp serve
claude mcp add --transport http fresha http://127.0.0.1:8787/mcp

然后可以向你的 Agent 提出类似请求：

Anna Smith 发邮件询问周五下午能否由 Sam 为她做剪发和染发。找到她，查看两项服务的空闲时间，并在我确认后预约最早的时段。

Sam 明天生病了。把他当天的时间都设为不可预约，并告诉我哪些客户可以由同事同时接待。

对比昨天和上周同一天按销售类型划分的销售额。标出超过 £50 的退款。

列出尚未回复的评价，并为每条评价拟一段简短回复。

REST API

fresha-mcp serve                   # http://127.0.0.1:8787, MCP at /mcp, docs at /docs

每个工具在 /api/v1/fresha 下都有自己的路由，路径与 cotlet.dev 上的托管 API 相同，因此针对其中一个 API 编写的代码也适用于另一个。路径部分和查询字符串是参数，JSON 请求体则可提供其余参数。

curl 'http://127.0.0.1:8787/api/v1/fresha/services'
curl 'http://127.0.0.1:8787/api/v1/fresha/appointments?from=2026-10-27&to=2026-10-31'
curl 'http://127.0.0.1:8787/api/v1/fresha/sales-summary?from=2026-10-01&to=2026-10-31'
curl -X POST http://127.0.0.1:8787/api/v1/fresha/blocked-times \
  -H 'Content-Type: application/json' \
  -d '{"team_member_id": "5652945", "start_at": "2026-11-03T13:00", "end_at": "2026-11-03T14:00", "title": "Lunch"}'

按名称调用任意工具，并将请求体作为其参数：

curl -X POST http://127.0.0.1:8787/api/v1/fresha/tools/list_clients -d '{"search": "smith"}'

• GET /api/v1/fresha/tools：列出所有工具及其路由、输入架构和示例回答。
• GET /docs：交互式 OpenAPI 文档；GET /openapi.json：供 n8n、Postman 或生成的客户端使用的架构。
• 回答均为 JSON。列表工具会返回 next_cursor；将其作为 cursor 传回即可获取下一页。

服务仅监听 127.0.0.1。若要从你的其他设备访问，请设置令牌；此后每个请求都需要包含 Authorization: Bearer <token>：

FRESHA_MCP_TOKEN=$(openssl rand -hex 24) fresha-mcp serve --host 0.0.0.0

Python 和示例脚本

直接使用 Python，无需服务端：

from fresha_api_mcp import call
from fresha_api_mcp.scripting import paginate, write_rows

services = call("list_services")["services"]
day = call("list_appointments", {"from": "2026-10-27", "to": "2026-10-27"})["appointments"]
clients = list(paginate("list_clients", {"sort": "name"}, "clients"))
write_rows(clients, "clients.csv")
call("add_blocked_time", team_member_id="5652945", start_at="2026-11-03T13:00", end_at="2026-11-03T14:00")

也可以从 shell 调用一个工具：fresha-mcp call find_available_slots service_ids='["25979401"]' date=2026-10-27 days=3，或使用 JSON 对象。当工具要求文本时，ID 会保持为文本。

时间均为商家的当地时间。2026-11-03T14:30 表示沙龙当地时间 14:30。带时区偏移的时间会转换为当地时间，回答中会包含 time_zone。

可直接使用的脚本位于 examples/。每个脚本都会输出 JSON 或简短列表；在适用时，可使用 --out file.csv 或 --out file.json，并支持 --help：

脚本	功能
tomorrows_appointments.py	按团队成员分组显示明天的预约。--date，--all 也包含已取消的预约。
book_from_message.py	按姓名、电子邮件或电话号码匹配客户，在指定时间范围内查找多项服务的可用开始时间；使用 --book 时，会在你确认后预订最早的时段。
team_member_out.py	团队成员无法到岗时，屏蔽其工作时段，并将每位客户改约给同一时间有空的同事。输出计划；--apply 会在每次更改前询问。
cancel_day.py	使用你提供的取消原因，取消某位团队成员当天的预约。先列出预约；--apply 会在取消每项预约前询问。
daily_sales.py	按销售类型汇总某一天的销售额，并与一周前同一星期几对比；超过限额的退款会标记出来。
lapsed_clients.py	列出 N 天内没有预约且没有已预约项目的客户，并显示其营销同意状态。--email-consent-only。
export_clients.py	将所有客户导出为 CSV 或 JSON。--search，--sort。
export_sales.py	将指定日期范围的销售列表导出为 CSV 或 JSON。
unanswered_reviews.py	按评分从低到高列出尚未回复的评价；--reply-to 可发布回复。

python examples/tomorrows_appointments.py
python examples/team_member_out.py --team-member-id 5652945 --date 2026-10-30 --block 09:00-18:00
python examples/lapsed_clients.py --days 90 --out lapsed.csv

按计划运行时，只要自己的电脑处于开机状态，就可以使用 cron：0 8 * * * cd ~/fresha-api-mcp-server && .venv/bin/python examples/daily_sales.py。

全部 17 个工具

ID 来自列表工具：list_services 中的 service_id、list_team_members 中的 team_member_id、list_clients 中的 client_id、list_appointments 中的 appointment_id、list_reviews 中的 review_id。fresha-mcp tools 会输出此列表，fresha-mcp tools --json 还会输出输入架构。

预约

工具	访问权限	REST 路由	功能
list_appointments	读取	GET /appointments	列出日期范围内的预约，并显示客户、服务、团队成员、价格和状态。
get_appointment	读取	GET /appointments/{appointment_id}	获取单个预约：客户、服务、团队成员、时间、状态、价格和备注。
find_available_slots	读取	GET /available-slots	按天查找一项或多项服务与团队成员的可用开始时间。
create_appointment	写入	POST /appointments	为客户预约服务，并指定服务、团队成员和开始时间。
reschedule_appointment	写入	POST /appointments/{appointment_id}/reschedule	将预约改至新的开始时间，也可以改由其他团队成员提供服务。
cancel_appointment	写入	POST /appointments/{appointment_id}/cancel	取消预约且不收取费用，也可以通知客户。
add_blocked_time	写入	POST /blocked-times	在团队成员的日历中屏蔽一个时段，避免他人预约。

客户

工具	访问权限	REST 路由	功能说明
list_clients	读取	GET /clients	企业的客户列表，可按姓名、电子邮件或电话搜索。
get_client	读取	GET /clients/{client_id}	单个客户的信息：联系方式、通知设置、预约统计、即将到来的预约和备注。
add_client	写入	POST /clients	将客户添加到企业的客户列表。
add_client_note	写入	POST /clients/{client_id}/notes	在客户档案中添加仅团队可见的备注。

服务目录与团队

工具	访问权限	REST 路由	功能说明
list_services	读取	GET /services	企业提供的服务，包括类别、时长和价格。
list_team_members	读取	GET /team-members	团队成员信息，包括角色、联系方式、提供的服务以及是否接受预约。

销售

工具	访问权限	REST 路由	功能说明
get_sales_summary	读取	GET /sales-summary	某个时段的销售摘要：销售额、退款、折扣、税费和各类付款。
list_sales	读取	GET /sales	日期范围内的销售（发票）：编号、日期、客户、状态和总额。

评价

工具	访问权限	REST 路由	功能说明
list_reviews	读取	GET /reviews	客户对企业的评价，包括评分、文本和回复。
reply_to_review	写入	POST /reviews/{review_id}/replies	对客户的评价发布公开回复。

create_appointment 会根据客户的通知设置，让 Fresha 发送预约确认；该工具没有控制此功能的开关。除非传入 notify_client: false，否则 reschedule_appointment 和 cancel_appointment 会通知客户。评价回复是公开的，评价者也会收到通知。添加客户、备注或屏蔽时间都不会发送通知。在 list_appointments 中，状态、团队成员和客户筛选条件仅适用于日期范围内的前 100 条记录；对于业务繁忙的沙龙，请缩小日期范围。

此版本不包含：Fresha Payments 的付款结算和钱包、结账和退款、产品、礼品卡、会员资格、候补名单、营销活动和班次。create_appointment 不接受预约备注；add_blocked_time 只能屏蔽单日且不支持重复；如果预约收取取消费或已支付定金，cancel_appointment 会拒绝取消。

有意不实现：Fresha 登录、电子邮件、密码和用户账户，以及任何会转移资金的操作（订阅、账单、付款结算、付款方式）。每个请求都会经过防护检查，拒绝对这些 Fresha 路径进行任何更改。

配置

变量	默认值	功能说明
FRESHA_MCP_HOME	~/.config/fresha-api-mcp	session.json 所在文件夹。
FRESHA_AUTH_TOKEN		fresha_partners_session Cookie 的值，用于替代 session.json。
FRESHA_PROXY		向 Fresha 发送所有请求时使用的代理，例如 http://user:pass@host:port。
FRESHA_MCP_READ_ONLY		1 会隐藏并拒绝所有会更改 Fresha 数据的工具（等同于 --read-only）。
FRESHA_MCP_TOKEN		serve 所需的 Bearer 令牌；若要监听 127.0.0.1 以外的地址则必须设置。
FRESHA_MCP_HOST、FRESHA_MCP_PORT	127.0.0.1、8787	serve 的地址。

安全与 Fresha 账户

• 你的密码不会传到此代码。 这里只会读取 Chrome 已保存的 Cookie，且仅限 fresha.com 的 Cookie。
• 会话文件由你保管。 session.json 创建时的权限为 0600。任何拥有该文件的人都能以你的身份操作 Fresha for business，因此请勿将其加入 git 或放在共享文件夹中。
• 默认仅限本地。 serve 绑定到 127.0.0.1；未设置 FRESHA_MCP_TOKEN 时，使用其他地址会被拒绝。
• 仅限 fresha.com。 fresha.com 以外的请求和重定向都会被拒绝。
• 只读模式。 --read-only 或 FRESHA_MCP_READ_ONLY=1 仅开放 10 个读取工具。
• 操作会影响真实用户。 预约、改期或取消操作可能会向你的客户发送消息，回复评价则会公开显示。MCP 客户端会在运行这些工具前询问确认；脚本则不会，因此请先用你自己的测试客户试用。

错误

REST API 会返回 {"error": "<code>", "message": "..."}。MCP 服务会将相同的代码和消息作为工具错误返回。

状态	代码	处理方法
401	auth_required, auth_expired	没有会话，或 Fresha 已将你登出。请在 Chrome 中登录 partners.fresha.com，然后运行 fresha-mcp connect。
403	app_permission_denied	你的 Fresha 角色无权执行此操作，例如没有报告权限却尝试查看报告。
403	scope_denied	服务以只读模式运行，或请求会修改你的 Fresha 账户本身。
403	target_blocked	Fresha 拒绝了请求或显示了机器人验证。在 Chrome 中打开一次该面板，然后重试。
409	captcha_required	Fresha 要求完成 CAPTCHA。请在 Chrome 中完成验证。
422	invalid_input	缺少参数或参数有误；消息会指出具体参数。
429	rate_limited	Fresha 正在限制此账户。请等待几分钟。
502	target_error	Fresha 返回了错误（其消息位于 message 中），或更改了其面板。运行 git pull 获取最新工具，或提交问题。

自托管或托管版本

	此仓库	Cotlet，托管版
工具	相同的 17 个	相同的 17 个
运行位置	在你的电脑上，电脑开机时运行	在云端，全天候运行
Fresha 会话	你的 Chrome，保存在本地文件中	你在欧盟的专属 Cloud Browser，配置文件使用 AES-256-GCM 加密
Fresha 更改其面板时	我们修复后运行一次 git pull	我们会为你修复，每天测试所有工具
确认	你的 MCP 客户端会在每次调用前询问	预约、改期、取消和回复评价都需等你确认；可按工具切换
适用对象	你电脑上的 MCP 客户端、本地脚本	Claude.ai 和 ChatGPT 连接器、n8n、Make、Zapier，以及任何 HTTP 客户端
适用用户	你，仅限非商业用途	团队、企业、代理机构
价格	免费	免费试用 7 天，含 2,000 个点数，无需信用卡；之后可购买一次性点数包，5,000 个点数起价 $29

在托管版本中，成功调用会消耗 10 个点数，失败调用免费；只要 Cloud Browser 启用了供 Agent 使用的应用，每天就会消耗 50 个点数。完整价格。

常见问题

Fresha 有官方 API 吗？ 没有公开 API。Fresha 不提供 API 或开发者文档（截至 2026 年 10 月 11 日核实）。其 Data Connector 附加服务按地点收费，通过 Snowflake 连接将你的数据同步到报告工具，但无法预约、改期或取消预约。详情：cotlet.dev/integrations/fresha-api-mcp-server。

有适用于 Claude、ChatGPT 或 Cursor 的 Fresha MCP 服务吗？ 有，这个服务在你的机器上运行：用于 Claude Code、Claude Desktop、Cursor 和 Codex 的 fresha-mcp mcp。ChatGPT 和 Claude.ai 连接器需要公开的 HTTPS URL，托管版 Fresha MCP 服务可提供该 URL。GitHub 上有一个社区服务，可从 Snowflake 读取 Data Connector 表格；它需要 Data Connector 附加服务，且不会写入任何内容。

我需要 Data Connector 附加服务吗？ 不需要。这些工具使用你自己的 partners.fresha.com 会话，发送的请求与面板发送的请求相同。

它能查找空闲时段并替我预约吗？ find_available_slots 会返回未来最多 14 天内，一个或多个服务连续进行且由同一位团队成员提供时的空闲开始时间。create_appointment 会预约其中一个时段。Fresha 可以按你的要求在其他预约时段上安排预约，因此请先确认时段。

我可以将 Fresha 客户或销售数据导出为 CSV 吗？ 可以：python examples/export_clients.py --out clients.csv 和 python examples/export_sales.py --from 2026-10-01 --to 2026-10-31 --out sales.csv。

它在英国以外也能用吗？ 可以。这些工具会从 Fresha 读取你工作区的时区和货币。如果有多个地点，日历工具会使用第一个地点。

为什么它需要我的 Chrome？ 它通过 Chrome 读取你的 Fresha 会话，无需你的密码和两步登录验证码。每次登录时只需使用一次 Chrome，而不是每次调用都使用。

Fresha 将我登出后会怎样？ 调用会失败并返回 auth_expired。如果启用了 Chrome 远程调试，服务会在下次调用时读取新的会话（Chrome 提示时点击 Allow）。否则，请重新运行 fresha-mcp connect。

它能在 VPS 或 Docker 中运行吗？ 技术上可以，使用粘贴的 cookie，或从你的电脑复制的 session.json 即可。但这样 Fresha 会看到你的会话来自数据中心 IP，看起来就不太像是你本人。若要始终在线运行，托管版会将你的会话保存在你自己的 Cloud Browser 中，并使用固定 IP。

我的 Fresha 账号会被封禁吗？ 请求会使用 Chrome 的指纹，并像你亲自点击一样逐个发送。没人能保证平台永远不会采取措施。请保持正常使用。

我可以将它用于自己的沙龙或客户吗？ 不可以。许可证仅允许非商业用途，而经营自己的业务也属于商业用途。若用于沙龙、团队或客户工作，请使用 Cotlet 或发送邮件至 [email protected]。

我可以随意使用这段代码吗？ 不可以。源代码公开，但许可证仅允许非商业用途：不得用于商业用途。

某个工具无法使用，或者我需要其他工具。 请提交问题，注明工具名称和错误消息。

许可证

PolyForm Noncommercial License 1.0.0。简而言之：

• **允许：**非商业用途：你使用自己的 Fresha 账号满足个人需求，或由慈善机构、学校、公共研究机构或政府机构使用。可以修改代码，并在相同许可证下分享。
• **不允许：**任何商业用途，包括经营自己的业务；客户项目；出售或提供该工具，或基于它构建的服务。

---

由 Cotlet（@cotletdev）维护。Fresha 是其所有者的商标。本项目为非官方项目，与 Fresha 无关联，亦未获得其认可或赞助。