jobber-mcp-server

Jobber MCP 服务

一个用于 Jobber 的 MCP 服务 — 将任何兼容 MCP 的客户端连接到您的 Jobber 现场服务数据。

这是什么？

一个 MCP（Model Context Protocol） 服务，可通过简洁、类型化的 API，让 AI 助手和 Agent 访问您的 Jobber 数据 — 包括客户、工作、发票和报价。

将它与 Claude Desktop、Cursor、Windsurf、Cline 或任何兼容 MCP 的客户端配合使用，即可通过自然语言询问业务数据、创建报价并管理现场服务运营。

为什么使用它？

• 内置 6 个工具 — 在一个服务中管理客户、工作、发票和报价
• 模拟模式 — 使用虚假数据即可立即试用，无需 Jobber 账号
• 自然语言查询 — “显示逾期发票”即可轻松完成
• 创建报价 — 无需打开 Jobber 即可创建并发送报价
• 客户查询 — 查找客户详情、联系信息和工作历史
• 兼容所有 MCP 客户端 — Claude Desktop、Cursor、Windsurf、Cline 等

快速开始

添加到您的 MCP 客户端配置中（例如 claude_desktop_config.json）：

{
  "mcpServers": {
    "jobber": {
      "command": "npx",
      "args": ["-y", "jobber-mcp-server"],
      "env": {
        "JOBBER_ACCESS_TOKEN": "your_token",
        "JOBBER_CLIENT_ID": "your_client_id",
        "JOBBER_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

或者先使用模拟数据试用（无需 Jobber 账号）：

JOBBER_MOCK_MODE=true npx jobber-mcp-server

在 Jobber Developer Portal 获取 API 凭据。

使用方法

向 AI 助手提出如下问题：

• “列出我的所有客户”
• “显示 client-101 的详情”
• “分配给 Alex Reyes 的工作有哪些？”
• “为 Northwind Roofing 创建一份报价：紧急维修 2 小时，每小时 $150”
• “哪些发票已逾期？”

工具

工具	描述
list_clients	列出客户，可选择搜索、潜在客户筛选条件和数量上限
get_client	根据 ID 获取客户信息，包括联系信息和近期工作
get_job	完整的工作详情：状态、负责人、日程安排、明细项
list_invoices	按客户和／或状态筛选并列出发票
get_invoice	完整的发票详情，包括明细项和付款状态
create_quote	为客户创建包含明细项的新报价

使用场景

日常运营检查

“显示今天的工作和任何逾期发票” — 每天早上全面了解需要处理的事项，无需一上来就登录 Jobber 控制面板。

客户调研

“Northwind Roofing 的业务历史如何？” — 在现场拜访或销售电话前，调出客户详情、近期工作和未结发票。

生成报价

“为 Chen 女士创建一份报价：清理排水沟，1 小时，$120” — 无需切换应用，即可在现场起草并发送报价。

发票审核

“显示所有超过 $500 的未付款发票” — 无需手动筛选 Jobber 的发票列表，即可查找逾期付款并跟进。

现场服务报告

“总结 Alex Reyes 本周的工作” — 无需手动提取报告，即可为团队会议或工资核算生成绩效摘要。

安全性

• 需要 OAuth 凭据 — Jobber API 使用 OAuth2。凭据通过环境变量传递，绝不会记录到日志中。
• 无法访问本地文件 — 不会读取或写入计算机上的任何文件（除非启用模拟模式）。
• 无法访问 Shell — 不会执行命令或启动进程。
• 模拟模式安全 — JOBBER_MOCK_MODE=true 使用虚假数据，不会调用 Jobber API。
• 开源 — 采用 MIT 许可证。可在 GitHub 查看代码。

故障排除

出现“Authentication failed”错误

确认 JOBBER_CLIENT_ID、JOBBER_CLIENT_SECRET 和 JOBBER_ACCESS_TOKEN 正确无误。令牌会过期，请前往 Jobber Developer Portal 查看新的凭据。

模拟模式下“未找到数据”

确保在环境或 MCP 配置中设置了 JOBBER_MOCK_MODE=true。模拟模式会自动创建示例客户端、工作和发票。

服务无法启动

确保已安装 Node.js 18+：node --version。如果使用 npx，请确保 npm 为最新版本：npm install -g npm@latest。

MCP 客户端无法连接

确认配置路径正确。macOS 上，Claude Desktop 使用 ~/Library/Application Support/Claude/claude_desktop_config.json；Windows 上使用 %APPDATA%\Claude\claude_desktop_config.json。更改配置后，请重启客户端。

响应缓慢

Jobber 的 GraphQL API 延迟约为 200-500ms。复杂查询（例如，列出客户及其完整工作记录）可能需要更长时间。使用带有 limit 参数的 list_clients 可加快初始查询速度。

Jobber API 设置

要与真实的 Jobber 账户配合使用：

1. 前往 Jobber Developer Portal
2. 创建应用并获取 client_id 和 client_secret
3. 完成 OAuth 流程以获取 access_token
4. 将凭据添加到 .env 或 MCP 客户端配置中

要求

• Node.js 18+
• 拥有可访问 API 的 Jobber 账户，或使用 JOBBER_MOCK_MODE=true 进行测试

开发

git clone https://github.com/friendlygeorge/jobber-mcp-server.git
cd jobber-mcp-server
npm install
npm run build
npm run inspect   # opens MCP Inspector for testing

许可证

MIT