Tradify by Cotlet

Tradify API 和 MCP 服务，可自托管

一个 Tradify API 和 Tradify MCP 服务，使用 Python 在你自己的电脑上运行，并通过你自己的 Google Chrome 会话工作。包含我们在 Cotlet 投入生产环境的全部 15 个 Tradify 工具：工作单和工作单状态、客户、含明细项的报价、根据报价创建发票、发送报价和发票邮件、收款，以及日程安排器。

Tradify 没有公开 API、API 密钥、webhook 或官方 MCP 服务。其会计连接器（Xero、QuickBooks、Sage）同步的是发票和账单，而不是工作单、报价或日程安排。本仓库提供：

• 面向 Claude Code、Claude Desktop、Cursor、Codex 和任何 MCP 客户端的 MCP 服务，支持通过 stdio 或 HTTP 通信。设置
• 位于 http://127.0.0.1:8787/api/v1/tradify 的 REST API，并在 /docs 提供 OpenAPI 文档。设置
• Python：call("list_invoices", {"status": "overdue"})，以及 examples/ 中 9 个可直接运行的脚本。

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

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

目录

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

工作原理

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

1. 像往常一样，在你自己的 Chrome 中登录 go.tradifyhq.com 上的 Tradify：输入用户名，点击 Continue，再输入密码。勾选 Keep me logged in。
2. tradify-mcp connect 通过 Chrome DevTools Protocol 连接到该 Chrome，读取 tradifyhq.com 的 cookie，并将其保存到 ~/.config/tradify-api-mcp/session.json，只有你的用户账户可以读取。它不会查看或存储你的密码或两步验证码。
3. 每次工具调用都会使用这些 cookie，通过 curl_cffi 向 Tradify Web 应用自身调用的 /api 发出请求；curl_cffi 会复制 Chrome 的 TLS 指纹。会更改数据的调用会携带防伪令牌，每次工具运行时都会重新读取。不会运行无头浏览器。

会话存储在一个名为 SessionId 的 cookie 中。启用 Keep me logged in 后，Tradify 会将其保留约一个月。Tradify 将你登出时，如果 Chrome 已开启远程调试，服务会再次从 Chrome 读取 cookie。

要求

• Python 3.11 或更高版本。
• Google Chrome 144 或更高版本，并已登录 go.tradifyhq.com。只要启用了调试端口，任何 Chrome 或 Chromium 都可以使用。
• macOS、Linux 或 Windows。
• Tradify 账户。我们使用公司所有者账户进行构建和测试。办公室用户可查看和执行 Tradify 允许该用户查看和执行的操作。由于 Tradify 会阻止未启用两步安全验证的账户发送报价和发票邮件，因此 send_quote 和 send_invoice 要求登录账户已启用两步安全验证（Settings > Security）。

安装

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

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

要使用 AI Agent（Claude Code、Codex、Cursor）进行设置？在此文件夹中打开项目，并让它设置代码库：AGENTS.md 会告诉它每个步骤，而且只有 Chrome 中的操作需要你来完成。

更新方法：git pull && pip install -e .。我们会将托管的 Tradify 工具的每项变更都复制到此代码库中。

连接 Chrome

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

1. 在 Chrome 中打开 chrome://inspect/#remote-debugging，并开启远程调试。这样，Chrome 就会接受此电脑上程序发起的 DevTools 连接，并在每次连接前征求你的许可。

2. 确保你已登录 go.tradifyhq.com。

3. 运行：

   tradify-mcp connect
   

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

Saved 6 Tradify cookies to /Users/you/.config/tradify-api-mcp/session.json
Signed in to Tradify as Dan Novak (Northside Plumbing)

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

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

选项 B：使用带调试端口的 Chrome

Chrome 不会在默认配置文件上打开调试端口，因此请启动一个单独的 Chrome，登录 Tradify 一次，然后连接到它：

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

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

对于 Tradify 来说，全新的配置文件相当于新设备，因此如果启用了 2-Step Security，登录时会要求输入验证码。--cdp 也接受 ws:// DevTools URL，例如通过 SSH 隧道连接到另一台计算机上的 Chrome。

选项 C：手动粘贴 Cookie

对于没有 Chrome 的服务端：在 Chrome 中打开 go.tradifyhq.com 的 DevTools，选择**Application > Cookies > https://go.tradifyhq.com**，复制 SessionId 的值，然后：

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

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

随时检查会话：

tradify-mcp status

MCP 服务

MCP 服务会列出每个工具及其输入架构、面向 Agent 编写的说明和提示。读取工具会标记为只读；会联系他人的工具（报价和发票邮件、Scheduler 预约）也会标记出来，以便客户端在运行前征求你的许可。

Claude Code

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

Claude Desktop

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

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

Cursor

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

Codex

~/.codex/config.toml：

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

通过 HTTP 连接

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

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

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

为 Sam Lee 在 12 Oak St 创建一项新工作：更换热水缸。安排 Mike Ross 在周四上午工作约四小时，并向 Sam 发送确认邮件。

根据我的笔记，为 14 Elm Rd 的浴室重新布线项目报价：按 Standard 计费费率计算 6 小时人工，安装 6 个单价 $24 的 LED 筒灯和一个 $85 的排气扇。发送前先给我查看草稿。

为本周所有已接受的报价创建 30% 的定金发票，跳过金额低于 $500 或已开具发票的项目，并在我检查清单后发送。

将我下面粘贴的银行转账记录到对应发票，然后列出所有仍逾期的发票，按客户汇总，并按逾期时间从早到晚排列。

REST API

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

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

curl 'http://127.0.0.1:8787/api/v1/tradify/jobs?status=to_invoice'
curl 'http://127.0.0.1:8787/api/v1/tradify/invoices?status=overdue'
curl 'http://127.0.0.1:8787/api/v1/tradify/appointments?from=2026-10-27&to=2026-10-31'
curl -X POST http://127.0.0.1:8787/api/v1/tradify/invoices/558f2199-6ca6-489e-bfdf-d4d11cd878e3/payments \
  -H 'Content-Type: application/json' \
  -d '{"amount": 300, "method": "Bank Deposit", "reference": "TRF 20261023"}'

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

curl -X POST http://127.0.0.1:8787/api/v1/tradify/tools/list_customers -d '{"search": "lee"}'

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

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

TRADIFY_MCP_TOKEN=$(openssl rand -hex 24) tradify-mcp serve --host 0.0.0.0

Python 和示例脚本

直接从 Python 调用，无需服务端：

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

overdue = call("list_invoices", {"status": "overdue"})["invoices"]
week = call("list_appointments", {"from": "2026-10-27", "to": "2026-10-31"})["appointments"]
jobs = list(paginate("list_jobs", {"status": "all"}, "jobs"))
write_rows(jobs, "jobs.csv")
call("update_job_status", job_id="d3bd2e39-af25-4cda-9daf-d9f758f8f0e5", status="complete")

也可以从 shell 调用一个工具：tradify-mcp call list_quotes status=accepted since=2026-10-01，或使用 JSON 对象。

时间采用你公司所在时区的当地时间（设置 > 公司）。2026-10-29T08:00 表示当地时间 8:00。带时区偏移量的时间会转换为该时区，答案会附带公司的时区偏移量。

examples/ 中提供了现成脚本。每个脚本都会输出简短列表或 JSON；在适用时，可通过 --out file.csv 或 --out file.json 指定输出文件，并可使用 --help 查看帮助。会更改 Tradify 数据的脚本只会显示执行计划，除非你传入 --apply 或 --send：

脚本	功能
overdue_invoices.py	列出所有逾期发票，按客户汇总金额并按时间从早到晚排序，同时标记超过上次提醒时间的发票。可用作待联系清单。
record_payments.py	根据 CSV 银行导出文件中的发票编号，将付款记录到发票。跳过未知或已结清的发票，以及金额超过应付金额的付款。使用 --apply 执行。
pay_and_close.py	在一张发票上记录付款，并在没有未付金额时将相关工作设为已完成。
job_from_call.py	查找或添加来电者，创建工作；传入 --start 后，会先检查员工当天的时间安排是否冲突，再为其预约。
quote_from_notes.py	根据包含工时和杂项费用条目的文本文件创建报价草稿；使用 --send 通过电子邮件发送。
deposit_invoices.py	为近期已接受报价且尚无发票的工作创建按百分比计算的定金发票。使用 --apply、--send。
tomorrows_schedule.py	按员工分组显示明天的 Scheduler 日程，包含工作、客户和团队备注。
export_jobs.py	将工作导出为 CSV 或 JSON。支持 --status、--search。
export_customers.py	将所有客户及其站点导出为 CSV 或 JSON。支持 --archived。

python examples/overdue_invoices.py
python examples/deposit_invoices.py --percent 30 --minimum 500
python examples/export_jobs.py --status to_invoice --out to_invoice.csv

如需定时运行，只要电脑开机，在自己的电脑上使用 cron 即可：0 18 * * * cd ~/tradify-api-mcp-server && .venv/bin/python examples/tomorrows_schedule.py。

全部 15 个工具

ID 来自列表工具：job_id 来自 list_jobs，customer_id 来自 list_customers，quote_id 来自 list_quotes，invoice_id 来自 list_invoices。员工以 Scheduler 上显示的全名标识。运行 tradify-mcp tools 可打印此列表；运行 tradify-mcp tools --json 可同时显示输入架构。

工作

工具	权限	REST 路由	功能
list_jobs	读取	GET /jobs	列出工作及其编号、客户、站点地址、状态和指派员工。
get_job	读取	GET /jobs/{job_id}	工作详情：描述、站点、任务、备注、预约、费用、关联的报价和发票。
create_job	写入	POST /customers/{customer_id}/jobs	为客户创建新工作。初始状态为“未指派”。
update_job_status	写入	PATCH /jobs/{job_id}/status	为工作设置内置状态或自定义状态。

客户

工具	访问权限	REST 路由	功能说明
list_customers	读取	GET /customers	客户资料，包含联系详情和站点。
create_customer	写入	POST /customers	创建新的客户资料，可选择包含联系详情和实际地址。

报价

工具	访问权限	REST 路由	功能说明
list_quotes	读取	GET /quotes	报价信息，包含客户、总额、报价日期、到期日期和状态。
create_quote	写入	POST /customers/{customer_id}/quotes	创建包含明细项的报价草稿。调用 send_quote 前不会发送任何内容。
send_quote	写入	POST /quotes/{quote_id}/send	批准报价并通过电子邮件发送给客户，同时附上在线接受或拒绝报价的链接。

发票和付款

工具	访问权限	REST 路由	功能说明
list_invoices	读取	GET /invoices	发票信息，包含客户、工作、到期日期、总额、已付款金额和应付金额。
create_invoice_from_quote	写入	POST /quotes/{quote_id}/invoices	根据已批准或已接受的报价创建发票草稿，可开具全部或部分金额。
send_invoice	写入	POST /invoices/{invoice_id}/send	批准发票并通过电子邮件发送给客户；如果已启用，还会发送付款提醒。
record_payment	写入	POST /invoices/{invoice_id}/payments	记录发票收到的付款，并减少应付金额。

日程安排

工具	访问权限	REST 路由	功能说明
list_appointments	读取	GET /appointments	指定日期范围内的日程安排预约，包含员工、工作、时间和备注。
schedule_appointment	写入	POST /jobs/{job_id}/appointments	在 Scheduler 中为员工预约工作，可选择通过电子邮件向客户发送确认信息。

send_quote 和 send_invoice 会通过电子邮件向客户发送内容。schedule_appointment 会向每位员工发送 Tradify 的“You've been scheduled”通知；只有设置 email_customer 时才会向客户发送电子邮件。其他写入工具都只在 Tradify 内部操作。create_quote 和 create_invoice_from_quote 创建的草稿不会发送给任何人。record_payment 不接受超过应付金额的付款，也不接受草稿发票的付款。报价的部分发票（percentage、fixed_amount、line_items）需要支持进度发票的套餐；Tradify 将此功能作为 Pro 套餐出售。

此版本不支持：价目表项目、套件和报价选项（报价可使用杂项和工时明细）；读取报价明细；编辑或删除报价、发票或客户；移动或取消预约；员工列表、工时表、成本核算、账单、采购订单、询价、定期工作和表单。

有意不实现：Tradify 登录信息、密码和两步安全验证，以及 Tradify 套餐和账单。每个请求都会经过防护检查，拒绝对 Web 应用的登录和账户路径进行任何更改。

配置

变量	默认值	功能说明
TRADIFY_MCP_HOME	~/.config/tradify-api-mcp	session.json 所在的文件夹。
TRADIFY_AUTH_TOKEN		SessionId Cookie 值，用于替代 session.json。
TRADIFY_PROXY		访问 Tradify 的所有请求所用的代理，例如 http://user:pass@host:port。
TRADIFY_MCP_READ_ONLY		1 会隐藏并拒绝所有会更改 Tradify 的工具（等同于 --read-only）。
TRADIFY_MCP_TOKEN		serve 所需的 Bearer 令牌；若要监听 127.0.0.1 以外的地址，则必须设置。
TRADIFY_MCP_HOST、TRADIFY_MCP_PORT	127.0.0.1、8787	serve 的地址。

安全与 Tradify 账户

• 你的密码不会传到此代码中。 这里只会读取 Chrome 已保存的 Cookie，且仅限 tradifyhq.com 的 Cookie。
• 会话文件由你保管。 session.json 创建时的权限模式为 0600。任何拿到此文件的人都能以你的身份操作 Tradify，因此请勿将其放入 git 或共享文件夹。
• 默认仅在本地运行。 serve 绑定到 127.0.0.1；如果没有 TRADIFY_MCP_TOKEN，则会拒绝使用其他地址。
• 仅限 tradifyhq.com。 系统会拒绝向 tradifyhq.com 之外的地址发送请求或重定向。
• 只读模式。 --read-only 或 TRADIFY_MCP_READ_ONLY=1 仅开放 6 个读取工具。
• 部分操作会触达真实用户。 已发送的报价或发票会进入客户的收件箱，之后无法在 Tradify 中删除，只能取消。MCP 客户端会在运行这些工具前征求确认；脚本不会，所以请先向使用你自己电子邮件地址的客户试用。

错误

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

状态	代码	处理方法
401	auth_required, auth_expired	没有会话，或 Tradify 已将你登出。在 Chrome 中登录 go.tradifyhq.com，然后运行 tradify-mcp connect。
403	app_permission_denied	Tradify 不允许此登录账户执行该操作。对于 send_quote 和 send_invoice：请先设置 2-Step Security。
403	scope_denied	服务以只读模式运行，或请求会更改你的 Tradify 登录状态。
403	target_blocked	Tradify 拒绝了请求，或显示了机器人验证。先在 Chrome 中打开一次 Web 应用，然后重试。
409	captcha_required	Tradify 要求完成 CAPTCHA。请在 Chrome 中通过验证。
422	invalid_input	缺少参数或参数有误；消息会指出具体参数。
429	rate_limited	Tradify 正在限制此账户。请等待几分钟。
502	target_error	Tradify 返回了错误（如果 Tradify 提供了错误消息，该消息会显示在 message 中），或更改了其 Web 应用。请在我们修复后运行 git pull 获取最新工具，或提交问题。

可自托管或托管服务

	此仓库	Cotlet，托管服务
工具	相同的 15 个工具	相同的 15 个工具
运行位置	在你的电脑上，电脑开机时运行	在云端，全天候运行
Tradify 会话	你的 Chrome 会话，保存在本地文件中	你在欧盟的专属 Cloud Browser，配置文件使用 AES-256-GCM 加密
Tradify 更改 Web 应用时	我们修复后运行一次 git pull	我们会为你修复，每天测试所有工具
审批	MCP 客户端会逐次调用征求确认	报价和发票邮件及 Scheduler 预订会等待你的确认，可按工具切换
兼容对象	你电脑上的 MCP 客户端、本地脚本	Claude.ai 和 ChatGPT 连接器、n8n、Make、Zapier，以及任何 HTTP 客户端
适用对象	你本人，限非商业用途	团队、企业、代理机构
价格	免费	免费试用 7 天，含 2,000 点数，无需银行卡；之后可购买一次性点数包，5,000 点数起价 $29

在托管版本中，成功调用消耗 10 点数，失败调用免费；Cloud Browser 在启用面向 Agent 的应用期间每天消耗 50 点数。完整价格。

常见问题

Tradify 有官方 API 吗？ 没有。Tradify 不提供 API、开发者文档或 Webhook（截至 2026 年 10 月 11 日核查）。它通过内置集成连接其他工具：QuickBooks、Xero、Sage、Stripe 和 Google Calendar。详情：cotlet.dev/integrations/tradify-api-mcp-server。

有适用于 Claude、ChatGPT 或 Cursor 的 Tradify MCP 服务吗？ 有，这个服务在你的计算机上运行：在 Claude Code、Claude Desktop、Cursor 和 Codex 中使用 tradify-mcp mcp。ChatGPT 和 Claude.ai 连接器需要公开的 HTTPS URL，托管的 Tradify MCP 服务可提供该 URL。

它能把我的 Tradify 工单和发票导出到其他工具吗？ 可以。python examples/export_jobs.py --status all --out jobs.csv 和 python examples/overdue_invoices.py --out overdue.csv 可生成 CSV 文件，REST API 也会将相同列表以 JSON 格式提供给 n8n 或任何 HTTP 客户端。

为什么 send_quote 会因 app_permission_denied 而停止？ Tradify 会在登录账号启用两步安全验证之前，阻止发送报价和发票邮件。请在 Tradify 的 Settings > Security 中设置手机号码，然后重新调用。该工具会在批准任何操作前停止，因此报价或发票会保持草稿状态。

我需要哪种 Tradify 套餐？ 这些工具能执行的操作取决于你的 Tradify 套餐。要根据报价开具部分发票，需要进度开票功能，该功能包含在 Tradify Pro 套餐中。使用免费的 Tradify Connect 套餐时，只有 Scheduler 可用。

它能在美国以外的地区使用吗？ 可以。Tradify 为所有国家/地区提供同一个 Web 应用，工具会从中读取你公司的时区和税率。

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

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

它能在 VPS 或 Docker 中运行吗？ 从技术上说可以，只需粘贴 Cookie 或复制计算机上的 session.json。但这样一来，Tradify 会从数据中心 IP 地址看到你的会话，这看起来就不太像是你本人在操作。若要始终在线运行，托管版本会将你的会话保存在你自己的固定 IP 云浏览器中。

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

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

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

某个工具出错了，或者我需要其他工具。 请提交问题，并注明工具名称和错误消息。

许可证

PolyForm Noncommercial License 1.0.0。简而言之：

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

---

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