Gradient MSP MCP

Gradient MSP + AI - 适用于 ChatGPT、Claude、GitHub Copilot、Microsoft 365 Copilot、Gemini，以及任何支持 MCP 的 Agent

非官方。由社区构建的 Gradient MSP API Claude Code 技能和 MCP 服务。与 Gradient MSP, Inc. 无关联，也未获得其认可或赞助。

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

通过终端调用 Gradient MSP Synthesize 供应商 API：批量推送用量并仅重建一次账单、本地推送偏差记录，以及门户和 SDK 不提供的警报到工单追踪。可与您已在使用的 AI 搭配使用 - ChatGPT（Plus/Pro+，此连接器重新发布前暂停；参见 mcp-install.md）、Claude Desktop、Codex、Claude Code、Claude Cowork 和 GitHub Copilot - 也可通过远程方式搭配 Microsoft 365 Copilot / Copilot Studio 和 Google Gemini 使用。免费、开源，可在笔记本电脑上运行。专为 MSP 所有者打造。无需编写代码。

适用于您的 Agent

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

MSP 所有者实际使用的六种 Agent（可自行安装，立即可用）：

您的 AI Agent	如何安装 Gradient MSP 技能
Claude Desktop	运行安装程序，然后前往 Settings > Extensions 注册 gradient-mcp（无需编辑 JSON）。
ChatGPT（付费方案）	此连接器重新发布前暂停：ChatGPT 需要 HTTP 模式，而此版本的该模式无需密码，会监听所有网络接口，并且您打开的网页可以访问它。参见 mcp-install.md 中的安全提示。
Codex CLI	粘贴下方的安装提示词。
Claude Code	粘贴下方的安装提示词。
Claude Cowork	粘贴下方的安装提示词。
GitHub Copilot（VS Code）	运行安装程序，在 mcp.json 的 servers 键下添加 gradient-mcp，然后选择 Agent 模式。

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

同样适用于 Microsoft 和 Google 技术栈

安装量很大，但先坦诚提醒：这条路径使用的是远程／企业版，而不是你刚安装的本地二进制文件。

Agent	所需条件
Microsoft 365 Copilot / Copilot Studio	暂停使用，直到重新发布此连接器：Copilot Studio 需要 HTTP 模式，而此构建版本中的该模式无需密码、会监听所有网络接口，并且可以从你打开的网页访问。请参阅 mcp-install.md 中的安全说明。
Google Gemini	Gemini CLI 在本地运行——与 Claude Code 相同。Gemini app 在远程运行，需要使用与 ChatGPT 相同的暂停启用的 HTTP 模式。请参阅 mcp-install.md。

原生支持 Skill 的 Agent（也已涵盖）： Hermes 和 OpenClaw 可直接读取此 Skill 的 SKILL.md，并且支持 MCP——请参阅下方的安装章节。也可通过 MCP 与 Cursor、Windsurf、Cline、Continue.dev 和 Zed 搭配使用。各工具的完整接入说明：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 上启动。每个工具都会调用配套的 gradient-cli。自 2026-09-18 起发布的版本会在安装包内附带此 CLI；较早的安装包只包含 MCP 服务，因此，如果你的安装包缺少配套程序，请先运行下方的路径 A 或路径 B 安装程序（或将 GRADIENT_CLI_PATH 设置为现有二进制文件的路径）。详情：#331。

下载 Gradient MSP MCP (.mcpb)——然后打开 Claude Desktop > 设置 > 扩展 并选择该文件。只需点击一次，无需 JSON 或命令行。（在 releases page 浏览所有 Gradient MSP 版本。）

更喜欢 Claude Code 插件？添加一次 marketplace，然后安装即可——立即生效，无需列出目录：

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

路径 A——向 AI Agent 粘贴一条提示词（推荐）

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

在此 Agent 工作区中安装来自 Servosity/msp-skills 的 Gradient MSP Skill 和 MCP 服务。如果此工作区使用 POSIX shell（macOS、Linux、WSL 或 Bash），运行 bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/gradient/install.sh)。如果使用 Windows PowerShell，运行 iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/gradient/install.ps1 | iex。然后按照 README 完成身份验证，并运行 gradient-cli --help 进行探索。

任何能够运行 shell 的 Agent 都可以使用相同的提示词。

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

Windows（PowerShell）：

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

macOS / Linux：

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

安装程序会将 gradient-cli（CLI）和 gradient-mcp（MCP 服务）放入你的用户 bin 路径。Claude Code、Codex 和 Cowork 会通过此目录中的 SKILL.md 发现 Skill。

验证：

gradient-cli --version

升级到最新版本

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

macOS / Linux：

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

Windows（PowerShell）：

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

Claude Desktop .mcpb 用户：下载最新的 .mcpb（见本节顶部），并在 设置 > 扩展 中重新选择。Claude Code 插件用户：/plugin update gradient@msp-skills。

添加到 Claude Desktop、GitHub Copilot、Gemini CLI、Microsoft 365 Copilot 或其他 MCP 客户端

安装程序运行后，请参阅 mcp-install.md 和 docs/which-agent.md，了解各 Agent 的连接方法——每个 Agent 都有一个专属章节，其中包括 GitHub Copilot 的 servers 键，以及远程 Microsoft 365 Copilot / Copilot Studio 的配置路径。Claude Desktop 的 Settings > Extensions 面板是最简单的配置方式；对于偏好编辑 JSON 的用户，mcp-install.md 中介绍了 MCP 配置块。

为 Hermes 安装

在 Hermes CLI 中：

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

在 Hermes 聊天会话中：

/skills install servosity/msp-skills/skills/gradient --force

Hermes 原生支持 MCP，因此也可以直接使用 gradient-mcp 服务——安装路径和环境变量相同。

为 OpenClaw 安装

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

从 https://github.com/servosity/msp-skills/tree/main/skills/gradient 安装 gradient 技能。该技能会通过 openclaw: frontmatter 块定义如何安装所需的 CLI（gradient-cli）。

OpenClaw 目前尚未普遍开放；frontmatter 配置已预先提供，会在 OpenClaw 发布时立即启用。

身份验证

设置 CLI 所需的凭据（从你的 Gradient MSP 门户获取）：

GRADIENT_TOKEN=<value> gradient-cli doctor

运行任何会操作数据的命令前，doctor 会确认凭据是否有效。即使凭据被拒绝，它也会以 0 退出，因此脚本应添加 --fail-on error。

此技能的功能

MSP 经常提出的问题	命令
一次性推送整个使用量计数文件并准确重建账单？	gradient-cli usage push --file ./counts.csv --agent
上两次推送之间，哪些账户的使用量发生了变化？	gradient-cli usage drift --agent
发送警报并确认 PSA 工单确实已创建？	gradient-cli alert send --account "123456789" --title "Backup failure" --wait --agent
已派发的警报中，哪些从未转为工单？	gradient-cli alert trace --stuck --agent
哪些账户未映射或缺少供应商 SKU？	gradient-cli hygiene unmapped --agent
我的集成是否已准备好切换为启用状态？	gradient-cli status ready --agent
为一个账户和服务添加单条临时单位计数？	gradient-cli billing <serviceId> --account-id "123456789" --unit-count 42
我的凭据是否有效，集成状态如何？	gradient-cli integration get --agent

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

与众不同之处

大多数 Gradient MSP 集成和 MCP 服务都会将每个问题代理为实时 API 调用。查询单条记录时这没问题；但规模增大后就行不通了，例如查询自上次推送以来哪些账户的计费单位发生了变化，或 200 条已派发的警报中有多少从未转为 PSA 工单。

此技能会将 Gradient MSP 同步到带有全文搜索的本地 SQLite 镜像，并在本地账本中记录每次推送的计数。汇总类问题只需查询一次本地数据：即时、离线，而且 AI 看到的是答案，而不是原始数据。usage drift、hygiene unmapped 和 alert trace --stuck 等复合命令可关联账户、服务 / SKU 映射及推送账本——无状态 API 封装无法做到这一点。

解决的痛点

账单对账是侵蚀 MSP 利润的持续成本：每个周期都有人从各个供应商处导出 CSV，手动将字段映射到 PSA，并祈祷自己发现了所有发生变动的席位。这一直是 r/msp 上经常讨论的话题，而 Gradient MSP 自己的研究指出，手动处理耗时最多比自动化多 90%——这也是 1,000 多家 MSP 使用 Synthesize 的原因。但 Synthesize 唯一可通过程序访问的接口是 PowerShell SDK，而且每个集成都需要单独的脚本项目，因此推动对账的操作都落在脆弱的一次性脚本中，且没有发送记录。

此技能弥补了这一缺口：

• usage push - 一次性推送包含计数的整个 CSV 或 JSON 文件，只触发一次账单重建。
• usage drift - 发票前预检：查看各账户的计数在最近两次推送之间发生了哪些变化。
• alert send --wait / alert trace --stuck - 派发警报并阻塞等待 PSA 工单创建；列出未成功创建的警报。
• hygiene unmapped - 汇总所有未映射账户和 SKU 缺口，形成一个工作队列。
• status ready - 在将集成切换为活动状态前，检查是否可以继续。

更详细的说明请参阅 pain-point.md。

常见问题

这能与 ChatGPT 配合使用吗？

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

这能与 Codex、Cursor、Windsurf、Cline、Copilot 或 Gemini 配合使用吗？

可以——它们都支持 MCP。跨工具安装命令见上方的对照表，详细说明见 docs/which-agent.md。

我需要懂编程吗？

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

我的 Gradient MSP 数据安全吗？

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

我需要哪些凭据，如何设置？

需要 Synthesize 供应商令牌。将 <vendorApiKey>:<partnerApiKey> 的 Base64 编码值设为 GRADIENT_TOKEN，或者设置 GRADIENT_VENDOR_API_KEY 和 GRADIENT_PARTNER_API_KEY，CLI 会为你生成令牌。GRADIENT_BASE_URL 是可选的。运行 gradient-cli integration get，确认凭据有效。

这会取代 Synthesize 门户或 Managed Billing Reconciliation 吗？

不会。映射审批和对账审核仍在 Synthesize 门户中进行（或由 Gradient 的 MBR 服务处理）。此 CLI 负责供应商和集成侧的工作：推送账户、服务和用量计数，审核已推送的内容，并追踪警报对应的 PSA 工单。它是门户的补充，不会登录门户。

这会触及 Gradient MSP API 的速率限制吗？

CLI 仅在你发出请求时才会调用实时 API；批量 usage push 会将账单重建推迟到最后，只调用一次，而不是每行调用一次。执行 sync 后，读取密集型操作会基于本地 SQLite 镜像运行。需要时，可使用全局 --rate-limit 标志限制每秒请求数。

费用是多少？

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

安全模型

层级	示例	建议的 Agent 策略
读取	integration get、vendor get、services get、accounts list、usage drift、alert trace、hygiene unmapped、status ready、analytics	允许
写入（常规）	usage push、billing、alert send、alerting、import、accounts create、accounts update、accounts update-one、services create、mappings create、mappings update、mappings update-bulk、integration update-status、vendor update	使用 --dry-run 预览，然后执行经过审核的写入操作
凭据／配置	auth set-token、auth logout（仅限本地凭据文件）	仅限人在环
破坏性操作	无——Synthesize 供应商 API 不提供删除命令	仅限人在环

最有力的控制措施是你授予 Gradient MSP 凭据的权限范围——CLI 只能执行这些凭据所允许的操作。完整详情（包括如何收紧权限）请见 governance.md。

状态

Beta 版。已根据 Gradient MSP API 接口进行验证，并正在每周 Build Sessions 中与 MSP 合作，验证其在他们自己的生产租户上实际运行的情况。请在 compoundingteams.com/build-sessions 报名参加。

---

标准。 符合开放的 Agent Skills 规范（Anthropic，2025 年 12 月；支持 40 多种 Agent）。兼容 MCP——可与任何支持 MCP 的 Agent 配合使用，包括 Hermes。已准备好支持 OpenClaw（frontmatter 已预先配置，等待 OpenClaw 发布）。

由 Servosity 维护。采用 Apache-2.0 许可证。使用 CLI Printing Press 构建。最后更新：2026-06-07。