VPSnet

vpsnet-mcp

用于管理 VPSnet.com 服务的 Model Context Protocol（MCP）服务。通过 VPSNet API，向 AI 助手提供 VPS 生命周期操作、托管应用、DNS 区域、域名注册和联系人、账单、API 密钥元数据、SSH 密钥配置及相关账户工具。

功能

• 280+ 个工具，涵盖 VPSNet 服务管理、托管应用、免费和付费 TLS 证书、Automatic SSL 订阅、DNS、域名、账单、API 密钥和账户操作
• 账户和个人资料管理
• VPS 生命周期管理（启动、停止、重启、重装操作系统）
• 套餐变更（可免费升级或降级；KVM/Firecracker 磁盘无法缩小）
• 服务反向 DNS（rDNS/PTR 记录）
• 正向 DNS 区域、记录、DNSSEC、模板、导入/导出和 DDNS 令牌
• 域名可用性、联系人、注册/转移/续费/恢复报价及付费确认
• 受发布限制的托管应用，支持安装、运行状况检查、事件和类型化生命周期操作
• SSH 密钥管理——部署密钥并直接访问服务器
• API 密钥元数据检查（密钥创建、变更和撤销仍仅限会话内操作）
• 备份、账单、发票
• 订购新的 VPS 实例
• 系统状态和定价

远程 OAuth 连接器

远程配置文件还包含受权限范围限制的 DNS、域名和证书管理、公共 SSH 密钥、服务器恢复及备份浏览功能。它使用与控制面板相同的客户 API；后端会对每个请求执行权限检查。

远程连接器使用 https://mcp.vpsnet.com/mcp，并通过 VPSnet 获取客户授权。请参阅远程 AI 连接，了解连接设置、 权限和支持的操作。 如需了解授权过期或被撤销，以及授权选项不可用时的处理方法，请参阅 重新连接和请求的权限。

可分发的插件 README、清单和技能均为英文。 请参阅目录发布准备情况，了解软件包验证和 发布者要求；请参阅支持的用例， 了解服务器、应用和网络场景。目录发布和提供商账户可用性与安装此源代码相互独立。

请参阅 AI 客户端设置，了解 Gemini CLI、Cursor、Kimi Code、Kiro、 Cline 及其他远程 OAuth 客户端。这些软件包共用相同的 VPSnet 端点和任务技能。npm 软件包提供本地 MCP 服务； 可安装的插件包也包含 AI 应用的清单和技能。

运行 python3 scripts/package-distribution.py，构建所有客户端包。 同一构建还会生成四个独立技能导入包， 供每次导入一个技能文件夹或 ZIP 的客户端使用。 输出包含校验和，并会标明每种格式。公开目录提交材料位于目录套件。

订购使用现有的 VPSnet 连接，并支持由客户控制的购买权限和支出限额。AI 会显示最终价格，并在从账户余额扣款前请求批准。可用性遵循应用的分发规则。

以下说明介绍现有的本地 stdio/API 密钥客户端。

前置条件

安装前，请确保满足以下条件：

1. Node.js 20 或更高版本

   • 检查：node --version
   • Linux/macOS：访问 nodejs.org 或使用包管理器
   • Windows：运行 winget install OpenJS.NodeJS.LTS，或从 nodejs.org 下载
   • 安装 Node.js 后，重启终端／编辑器

2. Claude Code（CLI 或 VS Code 扩展）用户：

   • 全局安装 Claude Code CLI：npm install -g @anthropic-ai/claude-code
   • 检查：claude --version

3. 有效的 VPSnet.com 账户和 API 密钥（请参阅获取 API 密钥）

凭据配置路径

VPSNET_API_KEY 是首选的、按次启动使用的凭据，优先级高于文件。 如需使用基于文件的配置，请将 VPSNET_CONFIG_DIR 设为包含 .vpsnet-mcp-key 或 .mcp.json 的绝对目录路径。密钥文件的优先级高于该 JSON 文件中的 mcpServers.vpsnet.env.VPSNET_API_KEY。或者，可通过 VPSNET_API_KEY_FILE 指定一个绝对密钥文件路径；如果显式指定的文件无法读取或无效，启动将失败，而不会改用其他账户。

如果未设置 VPSNET_CONFIG_DIR，则只会从进程的启动目录（cwd）读取文件。 对于 node /path/to/vpsnet-mcp/build/index.js 和 npx vpsnet-mcp，行为相同：不会搜索包的安装／缓存目录及其父目录。如果编辑器或 MCP 客户端从其他工作目录启动，请显式设置该目录。请勿将凭据文件纳入版本控制。 VPSNET_API_URL 的优先级高于同一 .mcp.json 文件中的 URL；两种来源均适用现有的受信主机和 HTTPS 检查。

托管应用程序

托管应用程序、手动 SSH、DNS、API 以及其他部署方式都是并列的能力。本文档和工具列表中的排列顺序不代表推荐顺序。请选择最符合用户所需结果、目标支持情况、现有状态及明确约束的方式。目录中的应用条目只是可用的托管方式之一，不应成为覆盖有效手动或自定义部署请求的理由。目录中的应用以 Docker 容器形式运行在客户的服务器上，并使用类型化的安装和生命周期工具。

读取应用程序需要 applications:read。安装和生命周期变更需要 applications:manage 及幂等键；普通的应用程序生命周期变更不属于付费 API 密钥操作。CPU、RAM 和磁盘数值是配置建议，并非安装门槛：受支持的应用程序在下单时仍可选择，即使资源低于这些数值也可安装。产品、操作系统、架构和运行时兼容性仍是硬性要求。变更为异步操作，因此请使用 get_application_installation 和 get_application_events 验证。使用 get_application_health 检查最新的容器健康状况，使用 get_application_logs 查看近期、大小受限的排障日志；还可选择只限定到一个精确的 Compose 服务。日志检查最多接受 500 行和 131,072 字节。这两种只读范围的检查会创建短期检查任务，因此 API 密钥必须允许 POST 请求。

安装详情包含应用程序及各容器的 CPU、内存、网络、重启和存储历史记录（在 worker 提供相关数据时），且记录范围有限。容器仅通过 Compose 服务和序号标识。经明确确认后，使用 configure_application_resource_thresholds 替换可选的显示阈值。未提供的值会清除相应阈值；这些阈值仅用于突出显示测量值，不会限制资源、触发服务器操作或影响计费。经明确确认后设置 email_enabled，即可在达到阈值时向账户发送一封邮件，并在指标恢复时再发送一封；同一阈值持续超标期间，不会因重复测量而重复发送。 使用 configure_application_access 更改已安装应用的访问方式。先读取安装信息，并传入当前修订版本和新的幂等键。platform_https 会分配一个不透明的 VPSnet 主机名，并自动配置 DNS 和 HTTPS；private 不设公网监听器；public_http 通过服务器的公网 IP 使用 HTTP；managed_https 使用符合条件的 VPSnet 管理的 DNS 区域。external_https 记录现有的、由客户管理的 HTTPS 地址；VPSnet 不会配置或验证其 DNS、TLS 证书或反向代理。

managed_https 访问方式还可以列出 additional_addresses（每个端点最多 4 个，每个应用最多 8 个）：这些是客户自有 VPSnet DNS 区域中的其他名称，每个名称都需包含 zone_id、name、action 和 approve_dns: true。name 为空或为 "@" 时表示该区域的裸域名，因此 example.com 可以与 www.example.com 并列。action 可以是 redirect（默认值；将请求以 301 重定向到主地址，并保留路径和查询参数）或 serve（打开同一应用）。添加或移除其他地址不会更改主地址。此列表代表完整的目标集合：若更改访问方式时省略 additional_addresses，已保存的地址就会被移除；如需保留，请再次传入这些地址。其他地址不支持用于任何其他访问方式，且 VPSnet 不会为此收费。

list_application_registry_credentials 只会公开私有注册表凭据的元数据。注册表令牌的创建和轮换特意不设为 MCP 工具：请使用 VPSnet 控制面板或直接调用 REST API，以避免令牌进入模型提示词或工具参数。元数据可以标识 Docker Hub、GHCR 或精确的自定义 HTTPS 注册表主机名。

客户配方是由客户拥有的 Compose 定义，与 VPSnet 目录蓝图分开管理。它们可以在目标工作节点上验证、保存为不可变修订版本、通过托管生命周期安装，并在不包含机密值的情况下导出。VPSnet 目录配方不可导出。容器发现范围受限且只读：它会报告客户和托管容器，但不会返回环境变量值或挂载信息，也不会接管或修改检测到的容器。受控接管是一个独立流程，包含准备、检查和明确确认，适用于符合条件的 Compose 项目。初始接管仅执行一次，但其确切的外部卷绑定会持续签入后续生命周期操作。只有在确认托管替代容器已完全接管后，恢复操作才会重启源容器；结果不确定时会默认拒绝操作。

仅当 get_application_installation 返回一个 type: "update" 的 available_actions 条目时，才可以执行不可变更新。获得用户明确确认后，使用准确的、已公布的 expected_blueprint_version 和 expected_upstream_version 调用 update_application，并提供新的幂等键。幂等键在客户端范围内全局唯一：只有重放完全相同的请求时才复用同一键，绝不可将其用于其他服务或操作。后端会选择并冻结符合条件的已发布版本；调用方无需提交镜像、标签或目标版本。 不会创建单独的应用备份。在受支持的 Firecracker 服务上， list_application_restore_points 会返回不透明的、应用一致的整台虚拟机夜间还原点，且对应当前安装的确切修订版本。 查看还原点免费，但 API 密钥需要 applications:manage 权限、启用付费操作、applications:restore 付费权限范围，以及完整访问权限，因为响应中包含账户余额。 quote_application_data_restore 会锁定确切费用，但不会扣款。restore_application_data 需要使用返回的报价令牌、相同的幂等键，并明确确认付款和数据替换。付费 API 密钥还需要 applications:restore、启用付费操作，并设置每日／每月支出上限。 该操作仅替换由工作进程派生的已声明应用数据，不包括机密信息和无关的 Docker／服务端数据，并且需要预留回滚空间。轮询 get_application_data_restore；needs_attention 状态仍处于锁定状态，不得视为成功。这些工具不会接受或公开 PBS 凭据、归档名称、设备或文件系统路径。

安装列表和详情响应会包含按平台划分的 capabilities 区块——data_restore、console、compose_adoption、custom_projects 和 log_service_filter——以及单独的 access.capabilities.can_configure 标志。应以这些标志为准，判断安装支持哪些功能，而不是尝试执行操作后再查看失败结果。

卸载会永久删除受管理的容器、配置、已保存的凭据和应用数据；现有的服务端备份会予以保留。调用 uninstall_application 需要设置 acknowledge_data_loss=true，且只能在获得用户明确确认后设置。

MCP 接口面向任务设计，并非对每个 REST 路由逐一镜像。旧版 SMS 微支付和宏支付回调集成仍可通过文档所述的 REST API 和控制面板使用，但有意未作为 MCP 工具公开。公开的登录前订单和域名搜索路由同样提供了经过身份验证的 MCP 对应接口，供需要执行账户操作时使用。

TLS 证书与 Automatic SSL

证书产品并不限于托管应用。可移植的 DV、OV 和 EV 订单可安装在由客户控制的 Web 服务器、代理服务器、邮件服务器、负载均衡器、API 或其他支持 TLS 的系统上。Automatic SSL 订阅则会连接 VPSnet 或其他服务提供商上的兼容 ACME 客户端，并在付费期限内持续更新短期证书。

符合条件的账户还可以通过 get_free_certificate_eligibility → preflight_free_certificate → create_free_certificate 申请免费的可移植 DV 证书。对于 API 或助手部署，请在目标位置创建 CSR，并将其私钥保存在该位置；MCP 只接收公钥 CSR，之后也只返回公钥证书链。由 VPSnet 管理的密钥支持无人值守提前续期，但只能通过门户在双重验证后导出。免费证书、付费证书文件、付费 Automatic SSL 和应用 Managed HTTPS 是独立的产品及生命周期管理界面。

使用 list_certificate_catalog 区分 portable_certificate 与 acme_subscription 方案。Automatic SSL 的订阅流程为 quote_automatic_ssl_subscription → order_automatic_ssl_subscription，必须使用完全不变的请求、报价令牌、幂等键，并明确批准付款。使用 list_automatic_ssl_subscriptions 和 get_automatic_ssl_subscription 查看状态。添加其他名称时，使用 quote_automatic_ssl_domain → order_automatic_ssl_domain；对于基础名称/www 或通配符/基础名称规则已覆盖的名称，API 会阻止重复付款。在最后 30 天内，符合条件的下一期订阅可通过 quote_automatic_ssl_renewal → order_automatic_ssl_renewal 办理，只有在批准确切的欧元总额后，才会从账户余额中预付。取消订阅、移除域名以及修正同类型域名，分别使用 cancel_automatic_ssl_subscription、remove_automatic_ssl_domain 和 replace_automatic_ssl_domain；如状态不明确，应使用 refresh_automatic_ssl_subscription 进行核对，绝不能凭空发起第二次变更。私有 ACME 服务器和 EAB 凭据保存在受双重验证保护的客户门户中，API 密钥和 MCP 无法访问这些凭据，因此它们不会进入模型上下文。

恢复整个服务

request_restore 是一项付费且具有破坏性的操作：它会从账户余额中扣除恢复费用，并用备份时间点的数据覆盖整个服务磁盘，导致此后写入的所有内容丢失。这是确认操作，而非价格查询——如果请求正文中没有明确确认，API 会拒绝请求；如果价格在披露后发生变化，API 会直接拒绝扣款。

此操作界面没有用于收集确认的对话框，因此工具不会自行生成确认信息。acknowledge_data_replacement 和 acknowledge_restore_charge 都必须设为 true，且只有在用户确实批准替换磁盘并支付费用后才能设置——这与 uninstall_application 中的 acknowledge_data_loss 规则相同。省略任一字段都会导致架构错误，因此无人值守的调用方无法在未确认的情况下触发扣款：系统甚至不会生成报价。

expected_total_charged 是你从 get_restore_status 读取并向用户展示的含 VAT total_charged，必须原样传回。调用前不要重新读取该值：它应当是客户同意支付的金额，而刚获取的数字会与当前价格一致，从而彻底失去校验作用。如果价格发生变化，恢复操作会以 restoreQuoteChanged 为由被拒绝，并返回当前总额，且不会扣款；应告知用户新金额，重新获得批准后再试。

浏览备份中的内容

查看备份内容免费，而且与付费还原备份完全无关。list_restore_file_points、browse_restore_files 和 get_restore_file_browse 只读取备份的目录列表：不会向账户收费，不会覆盖磁盘，也不会将文件放回服务器。目前仅支持 Firecracker VPS。

浏览操作是异步的。browse_restore_files 会创建一个持久化任务并将工作排入队列，因此即使备份和正在运行的服务器都未改变，它的 MCP 注解仍为 readOnlyHint: false。它会返回一个处于待处理状态的浏览 ID；请轮询 get_restore_file_browse，直到 state 为 succeeded。只有在该状态下才会有条目；状态为 failed 的浏览结果会包含 errorCode，且不含列表，不得将其当作空目录呈现。

目录可能包含海量文件，因此服务器会根据工作节点的能力选择每页返回 200 或 1,000 个条目。当 result.nextOffset 不为 null 时，请使用相同的 sourceBrowseId 和 directoryEntryId 再次调用，并将该游标设为 offset。向前翻页时，请使用 result.pageSize，不要假定每页有 200 个条目。进入子目录时，请使用 type: "directory" 条目的不透明 id；不接受文件系统路径。条目类型为 file、directory、symlink 和 unsupported。

文件夹搜索（filter 参数）会匹配所列目录中的条目名称——不区分大小写的子字符串匹配；绝不匹配路径，也不递归搜索。该功能依赖旧节点未报告的一项工作节点能力，因此 list_restore_file_points 会返回 searchAvailable。发送筛选条件前，browse_restore_files 会检查该标志；如果不支持搜索，就会失败并返回 serviceFileBrowseSearchUnavailable，而不会悄悄返回未筛选的列表，让人误以为是搜索结果。这些节点仍可正常浏览。

将选定文件还原到服务器是付费操作，因此本处有意不提供此功能；请使用 VPSnet 控制面板。

SSH 访问工作流

此 MCP 服务通过 VPSnet.com API 管理您的 VPS 基础设施，包括 SSH 密钥配置。将 SSH 密钥部署到 VPS 后，AI 助手可以直接通过其环境中的终端连接（例如 Claude Code 的 Bash 工具或 Cline 的终端）。

典型流程：

1. AI 读取本地计算机的公钥（~/.ssh/id_rsa.pub）
2. 通过 create_ssh_key 将其上传到 VPSnet.com
3. 使用明确授予远程 OAuth 所需 vm:exec 权限的 deploy_ssh_key 将其部署到 VPS（或者在使用 order_service 下单时传入密钥）
4. 直接连接：ssh root@<vps_ip>

大多数 AI 编码环境（Claude Code、Cline、Cursor、Codex）都内置了终端访问功能，因此部署密钥后，AI 可以立即通过 SSH 连接到您的 VPS，无需额外工具。

对于没有原生 SSH 访问功能的环境，可搭配 mcp-server-ssh，通过 MCP 工具直接连接服务器。

组合配置：

{
  "mcpServers": {
    "vpsnet": {
      "command": "npx",
      "args": ["-y", "vpsnet-mcp"],
      "env": {
        "VPSNET_API_KEY": "your_api_key_here"
      }
    },
    "ssh": {
      "command": "npx",
      "args": ["-y", "mcp-server-ssh"]
    }
  }
}

开始使用

选择您的环境：

• Claude Code（命令行） — 基于终端的 AI 编码
• 适用于 VS Code 的 Claude Code — VS Code 扩展
• Claude Desktop — 桌面应用
• 搭配 GitHub Copilot 使用 VS Code — Copilot Agent 模式
• Cline / Cursor / Windsurf / Roo Code / Codex — 其他客户端

以下本地 stdio 示例采用多种 MCP 客户端支持的 mcpServers 配置格式。请使用客户端原生的配置架构；VS Code 的 .vscode/mcp.json 使用 servers。如需配置客户 OAuth 和托管连接器，请参阅 AI 客户端配置。

{
  "mcpServers": {
    "vpsnet": {
      "command": "npx",
      "args": ["-y", "vpsnet-mcp"],
      "env": {
        "VPSNET_API_KEY": "your_api_key_here",
        "VPSNET_API_TIMEOUT_MS": "45000"
      }
    }
  }
}

claude mcp add vpsnet -- npx -y vpsnet-mcp

export VPSNET_API_KEY="your_api_key_here"
export VPSNET_API_TIMEOUT_MS="45000"

npm install -g @anthropic-ai/claude-code

claude mcp add vpsnet -- npx -y vpsnet-mcp

"vpsnet": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "vpsnet-mcp"],
    "env": {
        "VPSNET_API_KEY": "your_api_key_here",
        "VPSNET_API_URL": "https://api.vpsnet.com"
    }
}

{
  "mcpServers": {
    "vpsnet": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "vpsnet-mcp"],
      "env": {
        "VPSNET_API_KEY": "your_api_key_here"
      },
      "disabled": false
    }
  }
}

codex mcp add vpsnet --env VPSNET_API_KEY=your_api_key_here -- npx -y vpsnet-mcp

[mcp_servers.vpsnet]
command = "npx"
args = ["-y", "vpsnet-mcp"]

[mcp_servers.vpsnet.env]
VPSNET_API_KEY = "your_api_key_here"

codex mcp add vpsnet --env VPSNET_API_KEY=your_api_key_here -- bash -lc 'source ~/.nvm/nvm.sh >/dev/null 2>&1 && nvm use --silent 20 && npx -y vpsnet-mcp'

{
  "mcpServers": {
    "vpsnet": {
      "command": "npx",
      "args": ["-y", "vpsnet-mcp"],
      "env": {
        "VPSNET_API_KEY": "your_api_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "vpsnet": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "vpsnet-mcp"],
      "env": {
        "VPSNET_API_KEY": "your_api_key_here"
      },
      "disabled": false
    }
  }
}

{
  "servers": {
    "vpsnet": {
      "type": "http",
      "url": "https://mcp.vpsnet.com/mcp"
    }
  }
}

code --add-mcp '{"name":"vpsnet","command":"npx","args":["-y","vpsnet-mcp"],"env":{"VPSNET_API_KEY":"your_api_key_here"}}'

devin mcp add vpsnet https://mcp.vpsnet.com/mcp
devin mcp login vpsnet --scopes services:read

对于旧版 Cascade，请打开面板中的 Actions → Open MCP config file，并在 mcpServers 下添加一个服务器，设置 serverUrl: "https://mcp.vpsnet.com/mcp"。完成 OAuth 流程。Cascade 的工具总数上限为 100 个，因此请检查已启用的工具。上面的本地 stdio 示例使用的是单独的 API 密钥连接。

请根据所用界面，参阅官方 Devin 本地 MCP 指南或旧版 Cascade 指南。客户端身份验证和 VPSnet 兼容性仍需在实际客户端版本上验证。

Windows 用户

• 使用 PowerShell 或 CMD（而非 Git Bash）运行 claude mcp add 命令
• 配置文件位置：C:\Users\<YourUsername>\.claude.json
• 安装 Node.js：运行 winget install OpenJS.NodeJS.LTS，或从 nodejs.org 下载
• 安装 Node.js 后，重启终端和 VS Code
• Claude Code 扩展中的环境变量必须位于 .claude.json 的 env 对象中，不能设置为系统环境变量

环境变量

请求由运行此服务的机器发出，而非浏览器。如果部署限制了来源地址访问，Web 服务器可能会针对被拦截的请求返回 HTML 403 页面；此时工具结果会明确指出这一点（non_api_response: true、http_status: 403），而不会转发该页面。每个错误结果都包含 http_status；429 还会包含 retry_after。

身份验证、范围和付费操作

每个请求都会携带 X-API-KEY 标头（VPSNET_API_KEY）。

• **使用管理密钥。**其访问级别为 full（读取和更改）或 read（仅限 GET）。AI 范围密钥仅用于 VPSnet AI 助手推理， 在所有账户路由上都会被拒绝，因此这里的工具都无法使用此类密钥； 错误结果会携带 auth_problem，说明原因和解决方法。
• **细粒度范围只会缩小密钥的权限。**范围列表为空的密钥保留其访问级别 所允许的全部权限；列出范围（例如 dns:read、 services:manage）则会限制权限。X:manage 包含 X:read。网络管理是 例外：networking:read / networking:manage / networking:order 绝不会 由 full 或 read 隐含授予，必须明确授权。
• **付费操作需要通过单独的门槛检查。**下表中标记为 Paid 或 Quote 的 工具需要 full 访问级别的密钥、paid_operations_enabled、指定的付费范围 （vps:order、vds:order、ds:order、fc:order、domains:order、 domains:renew、domains:transfer、certificates:order、 applications:restore、services:restore、fn:invoke、 networking:order）、已配置的每日和每月支出上限，以及稳定的 idempotencyKey（使用相同的密钥重试结果不确定的请求，绝不要使用新的密钥）。 下单时先获取报价，再使用返回的 quoteToken 确认；确认前须向用户说明准确的 欧元总额。使用 list_api_keys 查看密钥的范围、付费范围、支出上限和速率限制。
• **速率限制。**请求按密钥进行速率限制（list_api_keys 中的 rate_limit， 即每分钟请求数）。遇到 HTTP 429 时，应等待 retry_after 秒后再重试， 不要立即重试。
• API 密钥永远不能创建、更改或撤销 API 密钥，也不会获得管理员访问权限。

工具

下表为自动生成：编辑 scripts/tool-scopes.json（或工具注册信息）并运行 npm run docs:tools；如果内容不一致，npm test 会失败。

Scope 是工具所需的细粒度 API 密钥范围（none = 任意管理密钥； a + b = 两者都需要；a or b = 根据对象而定，二选一）。Paid： Paid: x 会扣除账户余额，并需要付费范围 x 以及上述门槛条件； Quote: x 会生成报价但不扣费，不过仍受相同条件限制； 单独的 Paid 会使用 full 访问级别的密钥扣除余额，且不需要单独的付费范围； Needs paid scope: x 表示读取余额或价格数据的操作； Billed while kept 表示初始时段内免费，此后按量计费；其余情况均为 free。

账户

服务

托管应用

服务操作

服务设置

操作系统重装

套餐变更（免费）

续费与账单

订购

备份

恢复

服务文件

Firecracker 服务需要更新后的 Guest Agent，Cloud VPS（KVM）则需要切换到 VDS 文件管理器；files:read / files:manage 是显式授权项（空权限列表不包含这些权限）。

SSH 密钥

API 密钥

创建、更改和撤销 API 密钥需要通过浏览器/会话登录。使用 API 密钥进行身份验证的 MCP 连接无法执行这些操作。

免费 TLS 证书

为便于通过 API 或助手安装到不同环境，请使用 customer_csr，并将私钥保留在生成 CSR 的位置。托管式申请可以无人值守地续订，但 MCP 无法导出其私钥。证书签发是异步的，且受配额限制：轮询 get_free_certificate，按照 get_free_certificate_instruction 中的说明操作，不要将已排队的申请视为已签发。

自动 SSL 订阅

自动 SSL 是一种可移植的付费 ACME 订阅。它可与 VPSnet 或其他提供商的兼容客户端配合使用，并非仅限于托管应用。私有 ACME 服务 URL 和 EAB 凭据仅会在受双重身份验证保护的客户门户中显示。它们有意不作为 MCP 工具或 API 密钥响应提供，因此助手无法将其复制到模型上下文中。

付费 TLS 证书

付费证书是可移植的账户产品：客户可以将其安装在 Nginx、Apache、lighttpd、OpenLiteSpeed、HAProxy、Caddy、邮件、API、负载均衡器或其他 TLS 终端上。此类证书与附加到 VPSnet 托管应用的自动 HTTPS 相互独立。MCP 仅接受公有 PKCS#10 CSR；私钥必须由客户自行保管，且绝不能出现在工具参数或模型上下文中。报价响应包含以 EUR 计价的最终客户价格；下单需要明确批准，并使用相同的幂等键和短时有效的报价令牌。

域名

DNS

快照

服务救援

Firecracker Functions

按需服务器

在验证按需服务器生命周期期间，客户下单功能已禁用。当前选项说明不包含自动备份和快照，并且会限制通过 TCP 端口 25、2525、465 和 587 建立出站连接。现有会话仍可通过 list/get/delete 访问，以便进行清理。已禁用的兼容性架构中的固定 TTL 和预付费字段并不代表产品上线承诺；启用下单前，必须统一发布灵活时长和按用量计费的约定。

Guest Agent

历史记录

公共

SDN 网络

必须明确授予网络权限：networking:read 或 networking:manage；普通的 full/read 默认权限不包含这些权限。 先查看 capabilities，再读取确切的自有资源及其代次。 后端会强制执行租户所有权、可用性和服务器 2FA 锁定规则。 已接受、已付款和就绪是不同的状态；请轮询对应的操作或资源。 DNS 更改通过网络的 settings.dns_change 进行轮询。 新的私有／公有负载均衡器、VPN 和公有地址使用明确的 报价 → 通用结账 → 订单状态流程。报价工具始终会发送 prepare_after_payment=true：付款前不会进行任何资源配置。 展示报价中的准确 EUR gross_amount，获取批准后，将相同的 idempotencyKey、quote_id 和 quoteToken 传递给 order_network_product。 API 密钥还需要完整访问权限、已启用付费操作、 networking:order 权限以及支出限额。读取 get_network_payment_methods， 并选择 system=balance；API 密钥不允许使用非余额结账。 如果无法确定是否已确认，请使用原报价 ID 和密钥进行恢复。 对于 status=paid_pending、billing_state=captured 且 reason_code=network_product_ip_inventory_wait 的 SDN 订单，公有 IP 库存不足期间，款项会保留。使用相同的订单 ID 轮询 get_network_product_order；库存恢复后，后端会自动继续处理。 不要创建其他订单、再次扣款或手动重试。 如果状态为 manual_review 或 network_product_stock_reconciliation_required，则需要运营人员审核；这并不授权自动重试。

普通 VPS 订单会通过 get_service.stateProcess.waitingReason=public_ip_inventory 呈现此等待状态（也会同步显示在旧版 stateProccess 字段中）。轮询同一服务，不要重新下单。 stateProcess.attention=true 表示需要运营人员处理。付款成功或创建请求已接受，并不代表服务器已就绪。

公有负载均衡器层级 alb_proxy_3／alb_proxy_5 使用请求类型 proxy_lb；私有层级 nlb 使用 private_lb。可用性和价格以实时产品目录为准。 旧版未付款的设备创建端点不能替代结账流程。

获取设备配置是一次性的管理操作，尽管其 HTTP 方法是 GET。在 MCP 外部生成密钥对，只提交 X25519 公钥，保存返回的密文封装数据，并在对话外解密。此类工具不会请求或解密私钥及明文 WireGuard 配置。响应不确定时，绝不要自动重复获取操作。

当前版本的后端不支持客户网络重命名、现有端口的固定 IP 编辑、设备重试或原生站点到站点 API。固定 DHCP 地址在附加时选择；移除并重新创建附加项需要单独批准，且不属于原位编辑。旧版未付款的负载均衡器／VPN 创建路由、旧版付款前库存购买，以及通过 API 密钥启用自动续费，均不会开放。现有公有地址绑定管理仍然可用；新公有地址使用账户所有权和通用结账流程。工具出现在列表中，并不意味着后端功能开关已启用。

操作示例

每个示例都包含对助手的请求，以及它调用的工具。

订购 VPS（先报价，再确认）

订购最便宜的 Cloud VPS，安装 Debian 并使用我的 SSH 密钥，从余额支付。

1. 调用 get_order_plans 查询产品，然后调用 get_order_options 查询所选方案的选项 （OS、周期、资源 ID），并调用 list_ssh_keys 获取密钥 ID。
2. 调用 order_service，并传入 plan、os、period、resources、sshKey（或 rootPassword，不能同时传入两者）、payment: { payment: 1, successUrl: '', cancelUrl: '' } 和稳定的 idempotencyKey。首次调用会返回报价，但不会扣款。 API 密钥需要具备 vps:order（或 vds:order、ds:order、fc:order）权限和消费上限。
3. 显示准确的欧元总价（含税）和计费周期。客户批准后，使用返回的 quoteToken、expected_total_eur 和 acknowledge_charge: true，重试参数和密钥均未更改的订单。 如果结果未知，请在控制面板中检查原始尝试；不要创建新的密钥来重试。
4. 轮询 get_service，查询返回的订单号；付款已接受不代表服务器已就绪。

网络服务（先报价，再订购）

在我的网络中添加一个私有负载均衡器，并从余额支付。

1. 调用 get_networking_capabilities、list_network_products 和 get_network_payment_methods（选择 system=balance 的支付方式）。
2. 调用 quote_network_product，传入 kind（private_lb、proxy_lb 或 vpn_gateway）、 tier 和 idempotencyKey；显示报价中的欧元 gross_amount。
3. 获得批准后，调用 order_network_product，传入相同的 idempotencyKey、 quote_id、quoteToken、余额 payment 和 acknowledge_charge: true。 如果结果不确定，请使用原始 quote_id 调用 find_network_product_order， 然后轮询 get_network_product_order。绝不要重复购买。

DNS 记录插入或更新

将 www.example.com 指向 203.0.113.10，TTL 设为 5 分钟。

1. 调用 list_dns_zones 查找 zone_id，然后调用 get_dns_zone 检查 现有记录及其 ID（需要 dns:read）。
2. 要添加 A 记录值，请调用 upsert_dns_record，并传入 zone_id、name: "www"、 type: "A"、content: "203.0.113.10"、ttl: 300（需要 dns:write）。 不同的内容会新增一条记录，并保留现有值。若名称、类型和内容三元组相同，则会更新 TTL 和注释， 并在记录已禁用时重新启用它。要替换现有值，请使用其准确的 record_id 调用 update_dns_record，并传入所需的名称、类型、内容和 TTL。
3. 调用 get_dns_zone 读取并确认所需记录，或调用 get_dns_zone_history 查看变更。

对于正在等待验证、但其所有权 TXT 值已丢失的区域，请先读取 get_dns_zone.zone.verification.record.value。仅当该值为 null、无法恢复，或客户要求轮换时，才使用 reissue_dns_zone_verification。该工具同时支持 pending_verification 和 verification_expired；旧值将不再被接受。请在 zone.verification.next_step 指定的位置更新 TXT 记录，然后调用 verify_dns_zone。仅重新签发不会验证该区域，也不会重置其状态。

订购付费证书

为 example.com 购买一张一年期 DV 证书；CSR 由我自行生成。

1. 调用 list_certificate_catalog 和 get_certificate_catalog_product，选择 产品并查看其当前欧元报价。
2. 调用 quote_certificate，传入 product_id、offer_id、offer_generation、 common_name（以及任何 alternative_names）、公开的 PKCS#10 csr、 自有联系人 ID 和 idempotencyKey（需要 certificates:order 权限、付费操作权限和消费上限）。 绝不要发送私钥。
3. 用户批准准确总价后，调用 order_certificate，传入相同的请求和 idempotencyKey、quote_token、payment，以及 acknowledge_exact_quote_and_payment: true。
4. 调用 get_certificate_validation（例如通过 upsert_dns_record 发布验证质询）， 证书签发后调用 download_certificate。

获取 API 密钥

1. 登录 vpsnet.com
2. 前往 Account > API Keys
3. 点击 Create API Key
4. 为密钥命名并复制密钥

密钥只会显示一次，请妥善保管。

故障排除

Claude Code VS Code 扩展中未显示 MCP 工具

1. 安装 Claude Code CLI：npm install -g @anthropic-ai/claude-code
2. 验证：claude --version 应显示版本号
3. 通过 CLI 添加服务：claude mcp add vpsnet -- npx -y vpsnet-mcp
4. 完全重启 VS Code（不要只重新加载窗口）
5. 检查 ~/.claude.json 中的配置是否正确

claude: command not found

全局安装 Claude Code CLI：

npm install -g @anthropic-ai/claude-code

确认 PATH 包含 npm 全局软件包。在 Windows 上，安装后请重启终端。

环境变量不起作用

对于 Claude Code 扩展，环境变量必须放在 .claude.json 中的 env 对象内，而不能是系统环境变量：

"vpsnet": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "vpsnet-mcp"],
    "env": {
        "VPSNET_API_KEY": "your_actual_key_here"
    }
}

API 密钥错误

此服务需要管理 API 密钥。下方列出的每种故障都会由工具通过 auth_problem 对象报告原因和解决方法，因此请查看该对象，而不要根据 HTTP 状态码猜测。

工具故障会携带 isError: true，同时保留 API 错误详情和恢复指引。对于结果未知的变更操作，必须先检查结果，再进行下一次尝试。服务订单号必须从 list_services 复制；支持 ASCII 字母、数字和连字符，包括带有多个订单后缀的订单号。格式错误或过长的 URL 标识符会在发送 API 请求前被拒绝。

• 确认密钥正确（以 vpsnet_ 开头，后接 43 个字符）
• 密钥创建时只会显示一次；如果丢失，请创建新密钥
• 检查密钥是否已过期（Account > API Keys）

deploy_ssh_key 成功，但 SSH 仍然失败

• 所有 VPSnet.com 服务器都使用 root 作为 SSH 用户名
• 密钥部署是异步的；部署后请等待 15-30 秒再尝试 SSH 连接

fetch is not defined 或意外错误

此服务需要 Node.js 20+。如果默认的 node 版本较旧（使用 nvm 的环境中很常见），可以：

• 将 Node 20+ 设为默认版本：nvm alias default 20
• 或使用 Codex 部分中展示的 nvm 封装脚本

许可证

MIT