HaloPSA MCP

HaloPSA + AI - 适用于 Claude、ChatGPT、Codex、Cursor，以及任何支持 MCP 的 Agent

非官方。由社区构建的 Claude Code Skill 和 MCP 服务，适用于 HaloPSA、HaloITSM 和 HaloCRM API。与 Halo Service Solutions Ltd. 无关联，亦未获其认可或赞助。HaloPSA、HaloITSM 和 HaloCRM 是 Halo Service Solutions Ltd. 的商标。

_{▶ 观看 30 秒演示 - 演示数据为模拟数据；展示的每条命令都存在于实际 CLI 中。}

为你现有的 AI 添加 HaloPSA 工单分类、SLA 违约预防、按客户端划分的情境感知能力，以及跨客户端分析 - 支持 Claude Code、Claude Desktop、ChatGPT（Plus/Pro+，在此连接器重新发布前暂停；详见 mcp-install.md）、Codex、Cursor、Windsurf、Cline、Continue、Gemini 或 GitHub Copilot。免费、开源，可在笔记本电脑上运行。本地 SQLite 镜像让你的 AI 能回答 Halo 实时 API 无法一次性返回的跨客户端问题 - 准备 QBR 时不会触发速率限制。专为 MSP 所有者打造。无需编写代码。

兼容你的 Agent

安全提示（此连接器重新发布前）。 请勿运行 HTTP 模式 （--transport http），即使是在 localhost 上也不行。此版本没有密码， 会监听所有网络接口，而且早于浏览器重绑定防护功能， 因此你打开的网页可以访问它。MCP 工具也可以使用你的凭据进行更改。 请使用默认的 stdio 传输方式。如果你为远程 Agent 设置了隧道， 请将其关闭。修复即将推出。

MSP 所有者实际使用的五种 Agent：

你的 AI Agent	如何安装 HaloPSA Skill
Claude Desktop	运行安装程序，然后前往 Settings > Extensions 注册 halopsa-mcp（无需编辑 JSON）。
ChatGPT（付费套餐）	在此连接器重新发布前暂停：ChatGPT 需要 HTTP 模式，而此版本的该模式无需密码、会监听所有网络接口，并且你打开的网页可以访问它。请参阅 mcp-install.md 中的安全提示。
Claude Code	粘贴下方的安装提示词。
Codex CLI	粘贴下方的安装提示词。
Claude Cowork	粘贴下方的安装提示词。

ChatGPT 需要远程 HTTPS 服务，这意味着必须使用此连接器的 HTTP 模式；在连接器重新发布前，该模式已暂停：此版本的该模式无需密码、会监听所有网络接口，并且你打开的网页可以访问它。请参阅 mcp-install.md 中的安全提示。

也支持 Cursor、Windsurf、Cline、Continue.dev、Zed、GitHub Copilot 和 Gemini CLI - 以及 Hermes 和 OpenClaw，后两者均通过 MCP 和预配置的 Skill frontmatter 接入。各工具的完整接入说明：docs/which-agent.md。

使用多个 Agent？ 只需一条命令，即可安装到所有 51+ 个受支持的 Agent：npx skills add Servosity/msp-skills@latest（需要 Node.js，然后运行每个 Skill 对应的安装程序来安装 CLI/MCP 二进制文件）。请参阅 docs/which-agent.md。

60 秒完成安装

Claude Desktop 最快安装方式 - 一键安装 .mcpb

Claude Desktop 安装包： .mcpb 可在 macOS（Intel 和 Apple Silicon）、Windows x64 和 Linux x64 上启动。每个工具都会调用配套的 halopsa-cli。自 2026-09-18 起发布的版本会将该 CLI 打包在安装包中；较早的安装包只包含 MCP 服务，因此如果你的安装包缺少配套 CLI，请先运行下方的路径 A 或路径 B 安装程序（或将 HALOPSA_CLI_PATH 设置为现有二进制文件的路径）。详情： #331。

下载 HaloPSA MCP（.mcpb） - 然后打开 Claude Desktop > Settings > Extensions 并选择该文件。一键安装，无需 JSON，也无需命令行。（在发布页面查看所有 HaloPSA 版本。）

更喜欢 Claude Code 插件？添加一次市场，然后安装即可立即使用，无需列出目录：

/plugin marketplace add Servosity/msp-skills
/plugin install halopsa@msp-skills

路径 A - 将一条提示词粘贴到你的 AI Agent 中（推荐）

将以下内容复制到 Claude Code、Codex CLI 或 Claude Cowork 中：

在此 Agent 工作区中，从 Servosity/msp-skills 安装 HaloPSA Skill 和 MCP 服务。如果此工作区使用 POSIX shell（macOS、Linux、WSL 或 Bash），请运行 bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/halopsa/install.sh)。如果使用 Windows PowerShell，请运行 iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/halopsa/install.ps1 | iex。然后使用 halopsa-cli auth login 进行身份验证（在你的租户中打开 Configuration > Integrations > Halo PSA API，即可获取凭据），并运行 halopsa-cli --help 了解用法。

同一条提示词适用于任何能够运行 shell 的 Agent。

路径 B - 自行运行安装程序

Windows（PowerShell）：

iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/halopsa/install.ps1 | iex

macOS / Linux：

bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/halopsa/install.sh)

安装程序会将 halopsa-cli（CLI）和 halopsa-mcp（MCP 服务）放入你的用户 bin 路径。Claude Code、Codex 和 Cowork 会通过此目录中的 SKILL.md 发现 Skill；Skill 实际调用的是二进制文件。

验证：

halopsa-cli --version

升级到最新版本

安装程序始终会获取当前版本 - 重新运行即可升级：

macOS / Linux：

bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/halopsa/install.sh)

Windows（PowerShell）：

iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/halopsa/install.ps1 | iex

Claude Desktop .mcpb 用户：下载最新的 .mcpb（见本节顶部），然后在 Settings > Extensions 中重新选择。Claude Code 插件用户：/plugin update halopsa@msp-skills。

添加到 Claude Desktop、Cursor、Windsurf、Cline、Continue、Gemini 或 Copilot

运行安装程序后，请参阅 mcp-install.md 和 docs/which-agent.md，了解各 Agent 的连接配置方法。Claude Desktop 的 Settings > Extensions 面板是最简单的方式。

为 Hermes 安装

在 Hermes CLI 中：

hermes skills install servosity/msp-skills/skills/halopsa --force

在 Hermes 聊天会话中：

/skills install servosity/msp-skills/skills/halopsa --force

Hermes 原生支持 MCP，因此也可以直接使用 halopsa-mcp 服务 - 安装方式和环境变量均相同。

为 OpenClaw 安装

OpenClaw 已正式发布（GA）。直接从此仓库安装 Skill：

openclaw skills install git:Servosity/msp-skills/skills/halopsa@main

或者告诉你的 OpenClaw Agent（复制以下内容）：

从 https://github.com/Servosity/msp-skills/tree/main/skills/halopsa 安装 halopsa skill。metadata.openclaw frontmatter 声明了所需的 CLI（halopsa-cli）和环境变量；如果缺少任何内容，请运行 openclaw doctor。

openclaw 也原生支持 MCP（参阅 OpenClaw MCP 文档中的 openclaw mcp set），因此你可以将 halopsa-mcp 配置为与 Skill 并用的 MCP 服务。

身份验证

HaloPSA 使用 OAuth2 client_credentials。在你的租户中，通过 Configuration → Integrations → Halo PSA API 创建 API 应用程序（Authentication Method：Client ID and Secret，Services），然后：

HALOPSA_TENANT=<yourtenant> halopsa-cli auth login \
  --client-id <id> --client-secret <secret>

CLI 会缓存访问令牌，并在令牌过期前自动刷新。

此技能的功能

以结果为先，用一条命令回答每个问题：

MSP 总在问的问题	命令
接下来 24 小时内有哪些工单即将违反 SLA？	halopsa-cli sla breaching --within 24h
如何查看所有 Agent 和团队的调度情况？	halopsa-cli triage --team Support
现在谁的工作负荷过重？	halopsa-cli agent workload
如何在一个界面中了解这个客户的完整情况？	halopsa-cli client card "Acme Corp"
所有合同还剩多少时间？	halopsa-cli contracts burn
哪些客户有即将超期的滞留工单？	halopsa-cli tickets age-out
从今天早上到现在，Halo 有什么变化？	halopsa-cli tickets changed-since 9:00
这台设备的资产历史是什么？	halopsa-cli asset history <id>
技术人员应该关联哪篇知识库文章？	halopsa-cli kbarticle suggest --ticket 12345
首次填充本地 SQLite 镜像	halopsa-cli sync --full

完整的命令参考：guide.md。AI Agent 操作约定（--agent、--dry-run，以及何时应在执行更改前确认）请参阅 AGENTS.md。

有何不同

大多数 HaloPSA MCP 服务和 AI 集成都会将每个问题转发为实时 API 调用。查询单个工单没问题；但到了季度业务回顾（QBR）时，这种方式就会失效。此时你可能会问：“上个季度，所有 47 个客户中有多少张备份失败工单？按合同类型分组。”——这需要调用 47 次分页 REST 接口，还要应对 HaloPSA 的速率限制（限制没有公开文档，且因托管方式而异），并让模型在满是原始 JSON 的上下文窗口中反复查找。

此技能会将 HaloPSA 同步到一个支持全文搜索的本地 SQLite 镜像中。聚合类问题只需执行一次本地 SQL 联接：即时、离线，AI 看到的是答案，而不是原始数据。triage、client card 和 contracts burn 等复合命令可以联接工单、客户、合同、时间和资产数据——这是无状态 API 封装器做不到的。

它与 HaloPSA 内置的 ChatGPT 集成功能互为补充（该集成功能非常适合改写回复、标记情绪等单工单处理）。两者功能没有重叠。

解决的痛点

MSP 所有者反复提到的两个痛点：

• 服务成本的增长速度超过合同价值。 压力来自运营层面：队列超负荷、SLA 告急，以及未定价工作侵蚀每张工单的利润。
• 关键人员依赖。 “如果你最好的技术人员明天离职，30 天内客户会察觉吗？”对大多数 MSP 来说，答案是肯定的，因为情况信息掌握在某个人的脑海里——而在 PSA 中，其他人无法快速完成分流。

此技能让任何团队成员或其 Agent 都能用一句话获取 PSA 中跨实体的真实情况：triage / sla breaching 会提前显示即将违反 SLA 的工单；client card 可按需为任何团队成员提供一块掌握情况的面板；contracts burn 可及早发现未定价工作；agent workload 则让整个团队的队列一目了然。如何读取 PSA 中的信息，不再依赖某个人，而是转化为任何团队成员（或其 Agent）都能运行的技能。

常见问题

这能与 ChatGPT 配合使用吗？

此版本不支持。ChatGPT（Plus、Pro、Team、Business、Enterprise 和 Education 计划；Free 计划目前尚不提供 Developer Mode）只能通过 HTTPS 连接远程 MCP 服务，这意味着需要以 HTTP 模式运行 HaloPSA MCP 服务。此版本的 HTTP 模式无需密码即可使用，会监听所有网络接口，且你打开的网页也能访问它。因此，在连接器重新发布前，请勿运行该模式，也不要将其置于隧道之后；原因请见 mcp-install.md 中的安全说明。在此之前，请使用 Claude Desktop、Claude Code 或 Codex。

这适用于 Codex、Cursor、Windsurf、Cline、Copilot 或 Gemini 吗？

适用——它们都支持 MCP。跨工具安装命令见上方的表格，详细说明请参阅 docs/which-agent.md。其中也记录了特定工具的注意事项（Copilot 使用 servers 而非 mcpServers、Cline 在 Windows 上的 npx 问题、ChatGPT 的订阅等级和桥接程序）。

我需要懂编程吗？

不需要。推荐的安装方式是将一句话粘贴到 Claude Code 或 Codex 中——你的 Agent 会读取 SKILL.md 并完成安装。备用方式是每种操作系统对应的一行安装程序（bash 或 PowerShell）。这两种方式都不需要编写代码。你只需输入一次 HaloPSA API 凭据。

我的 HaloPSA 数据安全吗？

你的数据保留在自己的计算机上。CLI 和 MCP 服务都是本地二进制文件。SQLite 镜像存放在你的用户帐户下的目录中。AI Agent 只能看到 CLI 返回的内容——通常是查询结果，而不是原始批量数据。凭据从你的环境或 Agent 配置中读取；MSP Skills 绝不会将其打包进此代码库或传输到任何地方。

这会触发 HaloPSA API 速率限制吗？

几乎不会。HaloPSA 的速率限制没有公开说明，而且因云托管实例和自托管实例而异。此技能使用 sync --full 进行一次同步，之后进行增量同步；后续的分诊、SLA、客户端卡片和跨客户端分析查询都针对本地镜像运行，而非实时 API。使用 API 直通工具时会触发 429 错误的大批量查询，在这里会变成一次 SQL 联接。

这与 HaloPSA 内置的 ChatGPT 集成有什么不同？

HaloPSA 内置的 ChatGPT 集成非常适合处理单个工单——改写回复、总结单个工单、标记情绪倾向。MSP Skills 则是跨客户端分析 + MSP 所有者随时随地使用的解决方案：可查询数千个工单、联接 HaloPSA 与 Servosity 的多系统查询，以及 HaloPSA 界面中无法呈现的临时报告。两者相辅相成；你不必二选一。

可以在 Windows 上运行吗？

可以。上面的 PowerShell 安装程序适用于 Windows。CLI 和 MCP 二进制文件均为原生 Windows 版本。Windows 上的 Cline 用户可能需要使用 docs/which-agent.md 中记录的一个简单 npx 变通方案。

费用是多少？

免费。采用 Apache-2.0 许可证。你只需为使用的 AI Agent（Claude、ChatGPT、Codex 等）付费，费用由你的 AI 提供商收取，而非我们。

安全模型

此技能使用你创建并配置权限范围的 OAuth 应用向你自己的 Halo 租户进行身份验证。默认情况下，任何变更操作之前都会先进行发现和试运行。

层级	示例	建议的 Agent 策略
读取	triage、sla breaching、client card、contracts burn	允许
写入（常规）	工单更新、备注、分配	使用 --dry-run 预览，然后经审核后写入
破坏性操作 / 配置	删除、配置更改	仅允许人工参与

最强的控制措施是你授予 Halo OAuth 应用的权限范围——CLI 只能执行该应用获准执行的操作。完整详情（包括如何限制权限）请参阅 governance.md。

状态

已在线验证。Servosity（维护者）已在其生产租户上确认。更多 MSP 在我们的每周 Build Sessions 中实际运行该工具。请在 compoundingteams.com/build-sessions 报名。

---

标准。 符合开放的 Agent Skills 规范（Anthropic，2025 年 12 月；支持 40 多种 Agent）。兼容 MCP，可与任何支持 MCP 的 Agent 配合使用，包括 Hermes 和 OpenClaw，并已预先配置 metadata.openclaw frontmatter，因此可直接运行 openclaw skills install。

由 Servosity 为 MSP 社区维护。采用 Apache-2.0 许可。使用 CLI Printing Press 构建。有关供应商非关联声明，请参阅 TRADEMARKS.md。最后更新：2026-05-28。