Jobber MCP 服务器：将 Claude、ChatGPT 或 Copilot 连接到 Jobber

由 Adeocode 构建：专为家庭服务企业打造的定制软件

我们为 HVAC、管道、屋顶、涂料、围栏和园林绿化公司构建集成和内部系统，基于他们已经在使用的工具。客户拥有代码的所有权，包括这个连接器。预约 15 分钟通话

开源 Model Context Protocol 服务器，可让 Claude、ChatGPT 或 Microsoft Copilot 从 Jobber 读取实时数据：客户、工作、报价、发票、收入和时间表。用简单的英语提问，即可从你的账户中获得答案，无需将任何内容导出到聊天窗口。

TL;DR： 12 个工具。只读，因此不会更改你的账户。通过 stdio 在你自己的机器上运行，也可作为通过 Streamable HTTP 的远程服务器，供 ChatGPT 和 Copilot Studio 使用。每次查询都会对照 Jobber 的 10,000 点限额进行预算，而这一点是大多数 Jobber 集成都会搞错的地方。OAuth 令牌在静态存储时使用 AES-256-GCM 加密。无中继服务器、无中间人。MIT 许可，永久免费。

适用人群： 在 Jobber 上经营店铺的所有者和办公室经理，以及为他们构建系统的开发者。如果你能复制一段配置到配置文件中，就能使用它。

[!TIP] 不是开发者？你完全不需要是。

以下步骤假设你会编辑 JSON 文件。如果你不熟悉，我们可以为你完成设置：你自己的 Jobber 应用、范围受限的凭据，并让你团队中的一个人带你走一遍。

了解我们在 Jobber API 上构建的内容 或 预约 15 分钟通话

跳转至： 你可以问它什么 . 它有何不同 . 安全性 . 设置 . 工具 . 成本表 . 需要更多扩展？

你可以问它什么

连接后，这些问题就变成了一行提问，而不是九次点击。

资金

• 哪些发票已逾期超过 30 天？

• 我们现在被欠了多少钱？

• 上个季度我们开出了多少账单？

• 按月份显示今年的收入

报价

• 哪些报价发出去后再无回音？

• 仍在等待客户回复的最早报价是哪一份？

• 未结报价中积压了多少金额？

客户

• 调出 Harbour Coatings

• 总结我们与该客户的历史往来

• 上次我们向他们收取了多少钱？

• 查找这个电话号码对应的联系人

工作

• 本周日程上有什么？

• 上个月我们按状态承接了多少项工作？

• 有没有我还没查看的新请求？

• 目前有哪些工作尚未排期？

每个答案都来自每次请求时的 Jobber 实时数据。连接器不缓存任何内容，也不会存储你账户的任何信息。

Related MCP server: Jobber MCP Connector

它有何不同

Jobber 按查询成本来计量其 API，而不仅仅按请求次数。你拥有 10,000 点额度。它们以每秒 500 点的速度补充。另一个独立上限将你限制为每 5 分钟 2,500 次请求。

这比听起来重要得多。我们在生产环境中构建 Jobber 集成，并在其中一个集成中记录了每次调用的成本。一次 KPI 仪表盘加载就消耗了 13,456 到 20,762 点，涉及 41 到 52 次 API 调用。 仅仅一个界面，就要面对 10,000 点的预算。

接下来是几乎所有人都踩过的坑。当 Jobber 对你限流时，它返回 HTTP 200，并把错误放在响应体中。 重试库以状态码为依据，把 200 当作成功，结果什么都拿不到。

这个连接器正是围绕这两个事实构建的：

• 每个工具都会声明其最大成本，并在花费任何额度之前检查剩余预算。

• 会检测 200 响应中的限流信号，等待额度补充，然后重试一次。

• 每个工具都设有分页大小上限，因此一个问题不会耗尽下一个问题的额度。

• 如果等待时间会很长，它会明确说明并快速失败，而不是一直挂起。

完整测量数据是公开的：Jobber API 速率限制：生产环境实测

你还可以在下方查看 每个工具的实测成本。这些数字来自一个针对真实账户运行每个工具的脚本，而非估算。

安全性：它能做什么、不能做什么

它是只读的。 1.0 版仅提供只读工具。它可以查看、计数和汇总。它不能创建工作、发送发票或调整拜访时间，因此最坏的情况是答错，而不是做错。写入工具会逐一推出，每个都带有一个明确的批准步骤，并且每次都会被记录。

模型永远不会编写自己的查询。 每个 GraphQL 文档都是固定的，并在 src/jobber/queries.ts 中经过审查。模型只负责选择调用哪个工具、传递哪些参数，仅此而已。没有原始查询工具，这使得访问权限和 API 成本都可预测。

你的凭据保留在你自己的机器上。 你自行注册 Jobber 开发者应用。Jobber 账户管理员会通过 Jobber 自己的登录页面批准它，因此连接器永远不会看到密码。令牌在 ~/.jobber-mcp/ 下使用 AES-256-GCM 加密存储，密钥存放在操作系统钥匙串中，而不是以明文形式保存在磁盘上。

没有任何流量经过我们。 连接器在你的硬件上运行，直接与 Jobber 通信。中间没有 Adeocode 云服务，因为根本没有云服务。

每次调用都会在本地记录。 ~/.jobber-mcp/audit.log 会记录每次工具调用的时间戳、参数和结果。令牌和机密永远不会写入其中；find_client 的搜索词会经过哈希处理而不是存储，因为它可能包含客户的姓名或电话号码。你可以使用 get_audit_log 工具读回这些记录。

一个坦诚的限制。 连接器只能读取 Jobber API 暴露的数据。团队利用率、按人统计的工时，以及每项工作的成本或利润，都不在其中。这些需要连接器之外的工作，本页底部对此有说明。

环境要求

• Node.js 18 或更高版本：nodejs.org/en/download

• 一个 MCP 客户端：Claude Desktop、Claude Code、Cursor、ChatGPT（开发者模式）或 Microsoft Copilot Studio

• 一个具有 API 访问权限的 Jobber 账户，并且需要有人能在该账户上批准开发者应用。Jobber 将完整 API 访问权限限制在其最高套餐中，所以请先在 getjobber.com/pricing 查看你的套餐。

设置

三个步骤，第一次大约需要十五分钟。

第 1 步：注册一个 Jobber 开发者应用

1. 前往 developer.getjobber.com 并使用 Jobber 管理员账户登录。

2. 创建新应用。给它起一个你能认出来的名字，例如 Claude Connector。

3. 将重定向 URI 精确设置为 http://127.0.0.1:5679/callback

4. 保存，然后复制 Client ID 和 Client Secret。

第 2 步：将它添加到你的 AI 客户端

Claude Desktop。 打开你的配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

• Windows：%APPDATA%\Claude\claude_desktop_config.json

在 mcpServers 内部添加以下内容，使用你自己的值：

{
  "mcpServers": {
    "jobber": {
      "command": "npx",
      "args": ["-y", "@adeocode/jobber-mcp"],
      "env": {
        "JOBBER_CLIENT_ID": "your-jobber-client-id",
        "JOBBER_CLIENT_SECRET": "your-jobber-client-secret"
      }
    }
  }
}

如果已经配置了其他服务器，请在添加此块之前，在最后一个服务器后面加一个逗号。然后完全退出 Claude Desktop 并重新打开。

Claude Code： claude mcp add jobber -- npx -y @adeocode/jobber-mcp

Cursor： 在 Cursor 的 MCP 设置中使用相同的 JSON 块。

ChatGPT 和 Microsoft Copilot Studio： 两者都只连接远程服务器，因此请使用下面的 HTTP 传输。

第 3 步：登录一次

在新会话中说：

authenticate with Jobber

你的浏览器会打开 Jobber 的登录页面。Jobber 管理员批准该应用。当它显示连接成功时，返回你的助手并尝试：

which invoices are past 30 days?

之后如需检查连接，可要求 auth_status。

[!TIP] 卡住了，还是想第一次就把它做好？

我们会注册应用、将它接入你的账户，并带你团队中的一个人走一遍流程。然后我们会告诉你它仍然无法回答哪些问题——这通常才是有趣的部分。

查看 Jobber AI 服务 或 预约 15 分钟通话

HTTP 传输，用于 ChatGPT 和 Copilot Studio

ChatGPT 的开发者模式和 Microsoft Copilot Studio 都要求服务器可通过互联网访问，因此请以 HTTP 模式运行连接器，并将它们指向 <MCP_BASE_URL>/mcp。

TRANSPORT=http \
MCP_BASE_URL=https://your-host.example.com \
MCP_API_KEY="$(openssl rand -hex 32)" \
JOBBER_CLIENT_ID=your-client-id \
JOBBER_CLIENT_SECRET=your-client-secret \
npx -y @adeocode/jobber-mcp

在公开暴露它之前，请先阅读以下内容。如果没有 MCP_API_KEY，服务器会拒绝以 HTTP 模式启动，因为不设置它就会把 /mcp 以及它能从 Jobber 读取的所有内容开放给任何能访问该端口的人。只有当其他东西已经在其前面强制认证时，才设置 MCP_ALLOW_NO_API_KEY=true。/mcp、/oauth/start 和 /oauth/callback 会拒绝 Host 或 Origin 头与 MCP_BASE_URL 不匹配的请求，以此作为 DNS 重绑定保护。请使用 HTTPS：只有在使用 HTTPS 时，OAuth 回调的绑定 Cookie 才会被标记为 Secure。每个会话都绑定到创建时提供的 API 密钥的哈希，因此泄露的 mcp-session-id 无法单独重放；会话在空闲 30 分钟或绝对 24 小时后会被回收。/health 返回 {ok: true}，不返回其他任何内容。

可用工具

你的助手会根据问题自动选择这些工具。你无需按名称调用它们。

读取你的账户（8 个工具）

管理连接（4 个工具）

Resources

Pagination

每个列表工具都接受一个可选的 cursor。当记录数超过一页所能容纳时，响应会同时包含 note（“还有 N 条”）和 next_cursor。在下次调用时将该值作为 cursor 传回，并重复此操作，直到不再返回 next_cursor。

client_history 将其拆分为 jobs_cursor、quotes_cursor、invoices_cursor 和 payments_cursor，每个部分一个；requests_inbox 使用 cursor 获取新请求，使用 unscheduled_cursor 获取未排期的请求。payments_cursor 的行为与其他不同：付款按发票嵌套，没有客户端级别的连接，因此传入它会为付款较多的那个发票获取更多付款，且该响应仅包含 payments 部分。每笔付款都带有 invoice_id 和 invoice_number，以便对应回去。

Cost table

实测值，而非估算值。通过针对真实 Jobber 账户运行每个工具并记录每次调用的成本生成，基于上文所述的 10,000 点预算。

使用 npm run build && npm run measure-costs 重新生成。不要手动输入这些数字。

Configuration

每个变量都记录在 .env.example 中。如果你直接使用 npm start 运行构建后的服务器，而不是通过自行传递环境变量的客户端来运行，则 .env 会从已安装包目录中 package.json 所在的位置读取，而不是从你的工作目录读取。请将其放在那里，或在你的 shell 中导出这些变量。

Troubleshooting

“API 预算正在补充，请在 N 秒后重试。” Jobber 基于成本的速率限制正在发挥作用。连接器会跟踪预算，并自动等待不超过 5 秒的短暂补充，包括 Jobber 在 HTTP 200 内发送的 THROTTLED 响应。只有当等待时间超过此时，你才会看到此消息，此时它会快速失败而不是挂起。请稍后重试。

“Jobber 仅向顶级套餐账户开放此数据。” Jobber 将完整 API 访问权限限制在其顶级套餐内。请在 getjobber.com/pricing 查看你的套餐。

OAuth 循环回退到错误页面。 请检查 JOBBER_CLIENT_ID 和 JOBBER_CLIENT_SECRET 是否与你的开发者应用完全一致，并且注册到 Jobber 的重定向 URI 是否与连接器使用的 URI 匹配。在 HTTP 模式下，该 URI 由 MCP_BASE_URL 派生而来。

端口 5679 已被占用。 将 JOBBER_REDIRECT_PORT 设置为空闲端口，并更新 Jobber 应用上的重定向 URI 以与之匹配。

“令牌文件存在，但解密失败。” 加密密钥与写入令牌文件时使用的密钥不再匹配，通常是因为钥匙串条目被移除、机器更换或 ENCRYPTION_KEY 设置不同。请运行 logout，然后重新运行 authenticate。

Audit log

每次工具调用都会以 JSONL 格式写入 ~/.jobber-mcp/audit.log，目录权限为 0700，文件权限为 0600。访问令牌、刷新令牌、客户端密钥、密码和加密密钥永远不会被写入其中。请参阅 src/utils/auditLog.ts 了解脱敏列表。find_client 的 search_term 会经过哈希处理，而不是以明文存储，因此可以在各条目之间进行关联，而不会暴露客户的姓名、电子邮件或电话。请将此日志视为业务敏感信息，并相应限制对机器的访问。

文件超过 10MB 后会进行轮转：当前文件变为 audit.log.1，覆盖之前的轮转文件，并开始新的日志。这是单代轮转，不是完整的 logrotate 配置。可使用 get_audit_log 工具读回日志。当任何行解析失败时（例如写入在行中间被中断），响应中会出现 corrupted_lines 计数。

Need more than the connector?

这个连接器读取你的 Jobber 账户。它不会在这些数据之上构建任何东西，而老板们最关心的问题往往恰好超出 API 所暴露的范围：员工利用率、按人统计的工时、每个工作的成本和利润，或者一个因为后台同步到自有数据库而保持流畅的仪表盘。

这正是我们做的工作。查看我们在 Jobber API 上构建的内容，阅读包含完整工具列表和 FAQ 的概述，或预约 15 分钟通话，带上你最希望 Jobber 能够回答的问题。如果 Zap 能够覆盖它，你会先听到这个建议。

Free forever

本仓库中的代码保持 MIT 许可，其新版本也保持 MIT 许可。 这里没有任何功能被阉割、限时或为付费层级而保留。我们通过构建这个项目无法构建的系统来赚钱。

Supporting this project

我们不接受捐赠。如果它为你节省了时间，以下事情能真正帮到我们：

• 给仓库加星标。 其他商家就是这样找到它的。

• 告诉另一家使用 Jobber 的商家。

• 在我们处理不当的 Jobber API 场景下开一个 issue。

Who we are

Adeocode 为家庭服务企业构建定制软件：暖通空调、管道、屋顶、涂料、围栏、景观美化及周边行业。围绕商家现有运作方式构建的集成、仪表盘和内部系统，由客户完全拥有。

我们是独立开发者。我们与 Jobber、Housecall Pro、ServiceTitan 或 Anthropic 均无关联，也不会从它们那里收取任何推荐费。我们发布的所有关于其产品的内容都带有我们验证该信息的日期。

• 网站：adeocode.com

• 预约通话：与创始人交流 15 分钟

Contributing

欢迎提交 issue 和 pull request。如果你遇到这个连接器处理不佳的 Jobber API 边缘情况，请附带场景和示例请求开一个 issue。符合版本 1 范围的只读工具也欢迎以 pull request 形式提交。

Development

npm install
npm test
npm run build
npm run lint

src/jobber/queries.ts 中的每个 GraphQL 文档在发布前都会对照 Jobber 开发者中心 GraphiQL 中固定的 JOBBER_GRAPHQL_VERSION 进行验证。涵盖所有文档的完整重新验证已于 2026-08-26 完成，包括在分页和时区更改后的 schedule_lookup 和 requests_inbox。现在不再有 VERIFY-IN-GRAPHIQL 标记。

License

MIT (c) Adeocode。参见 LICENSE。