RepairDesk MCP 服务器

一个 MCP（模型上下文协议）服务器，可为任何兼容 MCP 的 AI 助手——Claude Code、Claude Desktop、Codex CLI、OpenCode、Cursor、Windsurf 或任何其他 MCP 客户端——提供对您的 RepairDesk 店铺数据的直接读写访问。将其指向您店铺的 API 密钥，然后就可以开始提问，例如 "查找工单 T-15423"、"发票 8821 上有什么逾期未付"，或 "把 iPhone 屏幕维修任务分配给 Dave"。

这不是 RepairDesk 的官方产品——而是一个由 RepairDesk 店铺为 RepairDesk 店铺构建的独立工具。不提供任何担保，使用风险自负（请参阅许可证）——但它每天都在实际运行一家真实维修店的工单队列，而不是一个概念验证。

目录

• 您实际可以用它做什么

• 工具参考

• 这不是什么

• 快速开始

• 手动设置

• 所有配置选项

• 故障排除

• 常见问题

• 安全性

Related MCP server: TicketAI

您实际可以用它做什么

一旦接入您的 AI 助手，您就可以直接与您的 RepairDesk 数据对话，而无需在网页界面中点击操作。以下是一些真实示例：

前台 / 分诊

• "查找工单 T-15423" — 完整工单详情：客户、设备、各设备状态、备注。

• "Sarah Miller 的手机状态如何？" — 按客户姓名/关键词搜索工单。

• "显示所有待处理或等待零件的工单" — 按状态筛选工单。

• "Dave 现在分配了什么任务？" — 按技术人员筛选工单。

• "调出 John 的联系方式" — 按姓名、电话或电子邮件查找客户。

工作流程 / 维修台工作

• "为 T-15423 添加一条诊断备注：已更换屏幕，电池测试正常"

• "将工单 T-15490 分配给 Dave"

• "将 T-15423 标记为已修复" — 服务器会先要求您确认，并提示此状态会在 RepairDesk 中自动触发客户短信/电子邮件。

• "为这位客户创建一张工单：iPhone 13，更换屏幕" — 同样，在实际创建之前需要确认。

财务 / 管理

• "上个月还有哪些发票未支付？"

• "发票 8821 的未结余额是多少？"

• "我们有 iPhone 13 电池的库存吗？" — 库存搜索。

• "列出我们所有的技术人员" / "我们设置了哪些支付方式？"

• "我们配置了哪些维修类别/设备类型？" — 在创建工单或判断某个设备型号在您的系统中是什么时，这是有用的上下文信息。

由于这是通过真正的 AI 助手而非固定仪表板运行的，您可以自然地串联这些操作——"查找所有仍有未结工单的客户的逾期发票"——助手会跨工具自行完成，而无需您手动对照两个屏幕。

工具参考

安全护栏： repairdesk_tickets_write 在应用状态更改之前要求 confirmed: true，并在目标状态是 RepairDesk 会自动通知客户的状态（已修复、待取件、已完成、等待客户、等待报价、已取消）时发出警告。您无需为此做任何事——只需在您的助手转达确认提示时回答"是"即可。

便捷细节： 工单查询/写入接受 RepairDesk 的订单 ID 格式（T-15423）或内部数字工单 ID——您无需知道自己拥有的是哪一种，服务器会为您解析。

这不是什么

这涵盖了 RepairDesk 的读取端以及核心工单工作流写入。它不涵盖估价、预约创建、POS/销售交易、库存写入、付款记录、工单图片/附件上传或 Webhook。如果您需要其中某一项，欢迎提交 PR。

快速开始

您不需要是开发人员也能运行此工具——只需能熟练地在终端中输入几条命令即可。总时间：约 5 分钟。

1. 安装 Node.js（如果尚未安装）

从 nodejs.org 下载并安装——选择"LTS"版本。这将同时安装 node 和 npm。要检查是否安装成功，请打开终端并运行：

node --version

您应该会看到类似 v20.x.x 的内容（18 或更高版本都可以）。

2. 获取代码

如果您有 Git：

git clone https://github.com/codeyoc/repairdesk-mcp.git
cd repairdesk-mcp

如果没有： 点击 GitHub 仓库页面上的绿色 Code 按钮 → Download ZIP → 将其解压到某个位置 → 在该文件夹中打开终端。

3. 获取您的 RepairDesk API 密钥

在您的 RepairDesk 管理后台中：设置 → API。复制那里显示的密钥——设置脚本会在下一步中要求提供。请像对待密码一样对待它：它授予对您店铺数据的完全读写权限（请参阅安全性）。

4. 运行设置脚本

node setup.mjs

这是最快的路径，可处理所有事项：如有需要，它会为您运行 npm install，询问您的 API 密钥，询问您使用的 AI 助手（Claude Code、Claude Desktop、Codex CLI 或 OpenCode），并自动为您写入配置——首先备份任何现有配置文件。如果您使用其他工具，它会打印出配置块供您自行粘贴。

如果您更愿意手动操作——或者您的客户端不是上述四种之一——请参阅下面的手动设置。无论哪种方式，如果您跳过脚本，请先自行运行 npm install。

5. 试用

向您的助手提问，例如 "使用 RepairDesk，列出我最近的 5 张工单"。如果它返回了真实的工单数据，就完成了。

手动设置

如果 node setup.mjs 已经为您成功运行，请跳过此部分。否则，请先在此文件夹中运行 npm install，然后手动配置您的客户端：

在任意位置运行以下命令，将路径替换为您解压/克隆文件夹的完整路径，将密钥替换为您真实的密钥：

claude mcp add repairdesk \
  --env REPAIRDESK_API_KEY=your_key_here \
  --env REPAIRDESK_USER_AGENT=YourShopName-MCP/1.0 \
  -- node /full/path/to/repairdesk-mcp/server.mjs

打开（或创建）适用于您操作系统的配置文件：

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

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

• Linux： ~/.config/Claude/claude_desktop_config.json

添加以下内容（如果文件不为空，请与 mcpServers 中已有的内容合并）：

{
  "mcpServers": {
    "repairdesk": {
      "command": "node",
      "args": ["/full/path/to/repairdesk-mcp/server.mjs"],
      "env": {
        "REPAIRDESK_API_KEY": "your_key_here",
        "REPAIRDESK_USER_AGENT": "YourShopName-MCP/1.0"
      }
    }
  }
}

保存文件，然后完全退出并重新打开 Claude Desktop（不仅仅是关闭窗口）。

编辑（或创建）~/.codex/config.toml 并添加：

[mcp_servers.repairdesk]
command = "node"
args = ["/full/path/to/repairdesk-mcp/server.mjs"]

[mcp_servers.repairdesk.env]
REPAIRDESK_API_KEY = "your_key_here"
REPAIRDESK_USER_AGENT = "YourShopName-MCP/1.0"

启动一个新的 Codex 会话并运行 /mcp 以确认其已连接。（Codex 也有交互式 codex mcp add 命令，如果您更喜欢使用它而不是编辑文件——请查看 codex mcp add --help 以了解您安装版本的确切标志。）

打开（或创建）适用于您操作系统的配置文件：

• Mac/Linux： ~/.config/opencode/opencode.json

• Windows： %APPDATA%\opencode\opencode.json

添加以下内容（如果文件不为空，请与 mcp 中已有的内容合并）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "repairdesk": {
      "type": "local",
      "command": ["node", "/full/path/to/repairdesk-mcp/server.mjs"],
      "enabled": true,
      "environment": {
        "REPAIRDESK_API_KEY": "your_key_here",
        "REPAIRDESK_USER_AGENT": "YourShopName-MCP/1.0"
      }
    }
  }
}

重启 OpenCode 以使其生效。

上面使用的 command/args/env 结构（Claude Code/Desktop）是事实上的标准——大多数 MCP 客户端都遵循它，只是配置文件位置不同。请查看您客户端的文档以了解该文件的位置；配置块本身应该可以直接使用。

请使用 server.mjs 的完整绝对路径（例如 /Users/you/repairdesk-mcp/server.mjs 或 C:\Users\you\repairdesk-mcp\server.mjs）——相对路径会失败，因为您的 AI 客户端不会从此文件夹内部运行。

所有配置选项

以下所有内容都放在客户端配置使用的 env/environment 块中（setup.mjs 会为您处理）——而不是 .env 文件，因为大多数 MCP 客户端不会自动读取 .env 文件。本仓库中的 .env.example 列出了相同的变量供参考。

备选方案：用配置文件代替环境变量。 如果你的环境变量配置起来不方便，可以在 server.mjs 旁边创建一个 config.json（已加入 gitignore）：

{
  "repairdesk_api_key": "your_key_here",
  "repairdesk_base_url": "https://api.repairdesk.co/api/web/v1"
}

该文件在每次 API 调用时都会重新读取，因此你无需重启服务器即可轮换密钥。当两者同时存在时，环境变量优先于该文件。

速率限制——100 次/分钟的问题

RepairDesk 文档规定的上限是每个 API 密钥每分钟 100 次请求（部分套餐允许 120 次——如果不确定，请查看你自己的套餐）。本服务器会自动为你处理这个问题：

• 每次出站调用都会通过一个单一的节流器排队，该节流器在请求之间至少等待 REPAIRDESK_MIN_INTERVAL_MS（默认 600ms ≈ 100 次/分钟）——因此请求大批量工单本身不会触发速率限制错误。

• 如果 RepairDesk 仍然返回 429（速率受限）——例如另一个工具也在用同一个密钥频繁请求——服务器会自动等待并重试一次，然后才放弃。

• 你无需配置任何东西即可正常工作。只有在你持续看到速率限制错误（调高它）或你确定你的套餐允许更高的上限并希望加快批量查询速度（调低它，谨慎操作）时，才需要修改 REPAIRDESK_MIN_INTERVAL_MS。

故障排查

"RepairDesk API returned 401 Unauthorized" / 响应中出现"Unauthorized" 你的 API 密钥错误、已被吊销，或未被正确读取。请仔细检查 RepairDesk 中设置 → API 里的密钥，并确认它在你的 MCP 客户端配置中拼写正确（没有多余空格，也不是仍然保留着 YOUR_REPAIRDESK_API_KEY_HERE）。任何配置更改后请完全重启你的 AI 客户端——大多数客户端不会实时重新加载 MCP 配置。

请求立即失败 / 看起来像是被拦截，而不是认证失败 RepairDesk 的 Cloudflare 会拦截 User-Agent 为空或看起来像默认值的请求。不要将 REPAIRDESK_USER_AGENT 设置为空字符串。

"RepairDesk API rate limit hit twice in a row (429)" 即使在内置重试之后，你的请求速度仍然超过了密钥的限制。请在配置中调高 REPAIRDESK_MIN_INTERVAL_MS（试试 1000）。

"Ticket T-XXXXX not found — could not resolve to internal ID" 请检查订单 ID 是否正确，并且确实存在于这个 RepairDesk 店铺中。如果你有内部数字 ID，也可以直接传入。

"RepairDesk API request timed out after 15000ms" 通常是网络/防火墙无法访问 api.repairdesk.co，或者 REPAIRDESK_BASE_URL 配置错误。请确认运行此服务器的环境能够访问该主机。

你的 AI 助手完全看不到该工具

• 确认 args 中的路径是绝对路径而非相对路径，并且确实指向 server.mjs。

• 确认你已在该文件夹中运行过 npm install（缺少 node_modules = 服务器无法启动）。

• 完全退出并重启你的 AI 客户端——不要只关闭聊天窗口。

• 直接在终端中运行 node /full/path/to/server.mjs——如果出错，你会看到实际问题，而不是客户端给出的笼统的"工具不可用"提示。

node setup.mjs 提示在 PATH 中找不到 claude/codex 这没关系——它会回退为打印配置块，供你手动粘贴（参见手动设置）。这只是意味着该 CLI 未安装或不在你的 PATH 中；并不代表 MCP 服务器本身有问题。

仍然卡住了？ 请在本仓库中提交一个 issue，附上错误信息（如果输出中任何位置出现你的 API 密钥，请先将其打码）。

常见问题

这是 RepairDesk 的官方工具吗？ 不是。它是独立构建和维护的，使用 RepairDesk 的公共 API。请自行斟酌使用。

运行这个需要付费吗？ 不需要——它只是发起你的 RepairDesk 套餐本来就允许的 API 调用。本项目不收取任何额外费用。（你的 AI 助手订阅，例如 Claude，是独立的，与本服务器无关。）

我可以将它用于 Claude 以外的工具吗？ 可以——MCP 是一个开放标准。setup.mjs 直接配置 Claude Code、Claude Desktop、Codex CLI 和 OpenCode；任何其他通过 stdio 支持 MCP 的工具（Cursor、Windsurf 等）也可以使用本服务器，只需按照手动设置中的手动配置即可。

我可以为多个 RepairDesk 店铺运行这个吗？ 可以——在 MCP 客户端中以不同名称注册多次（例如 repairdesk-store1、repairdesk-store2），每次使用各自的 REPAIRDESK_API_KEY。

我的 AI 助手会不会意外地给客户发邮件/短信？ 只有 repairdesk_tickets_write 能触发该操作，而且只能通过状态变更触发——这始终需要显式的 confirmed: true，并且当目标状态是 RepairDesk 的通知类状态之一时，工具描述中会明确标注。不会静默发生。

安全

你的 REPAIRDESK_API_KEY 拥有对你店铺客户和财务数据的完全读写权限。请将其保存在 MCP 客户端的环境配置中，切勿放入已提交的文件。config.json 和 .env 在这里被 gitignore 正是出于这个原因——如果你更喜欢用文件而不是环境变量，可以在本地使用它们，但不要提交填写好的副本。发现安全问题？请提交 issue（如果你的托管平台支持，也可以提交私密报告），而不是公开带有利用细节的 PR。

许可证

MIT——参见 LICENSE。按原样提供，不附带任何担保——你需自行负责如何针对自己的 RepairDesk 账户使用它。