Render Useful MCP

render-useful-mcp

一个适用于 Render 的模型上下文协议服务，提供 Render 官方公共 API 的所有端点，并额外提供少量高级工具，简化原始 API 中繁琐的工作流。

使用 TypeScript 编写。每个 API 工具都根据 Render 自己的 OpenAPI 文档生成，因此从设计上就确保了完整覆盖，并会一直保持完整。

213 个工具：包含 Render 公共 API 的全部 208 项操作（规范版本 1.0.0），以及 5 个用于简化原始 API 中繁琐流程的工作流工具。

📖 文档网站 · 工具目录 · llms.txt

---

为什么选择这个项目

大多数 API 封装只涵盖精选的部分端点，容易逐渐过时；一旦你需要作者遗漏的功能，就会陷入困境。

• 从设计上确保完整。 Render 自己的 OpenAPI 文档中的每项操作都会成为一个工具。你的密钥能够通过 API 执行的所有操作，开箱即用即可访问，无需选择启用。
• 模型易于使用。 名称可以模糊匹配到 ID，工作区 ID 会自动填入，可以通过一次调用等待部署完成，发生故障时也会返回提示，而不只是状态码。
• 可按需收窄范围。 默认启用所有工具集；RENDER_MCP_TOOLSETS 和 RENDER_MCP_READ_ONLY 用于有意限制可用范围，而不是控制是否开放功能。
• 如实说明风险。 MCP 的破坏性、只读和幂等标注根据真实的 HTTP 语义推导，客户端可以据此合理地决定是否自动批准操作——包括会替换整个集合的 PUT 请求，此时调用方省略的所有内容都会被删除。日志中的密钥会被隐藏。

安装

这两个按钮都会预填一个占位 API 密钥，请在安装后替换它。

Claude Code — 全局安装，这样每个项目中都能使用：

claude mcp add render --scope user -e RENDER_API_KEY=rnd_your_key -- npx -y render-useful-mcp

关键在于 --scope user。Claude Code 默认使用 local 范围，只会为当前目录注册服务，因此它只在安装目录中可用，在其他目录中则不可用；这通常就是新添加的服务看似消失的原因。三个范围如下：

范围	标志	所在位置	可用范围
用户（全局）	--scope user	用户配置	每个项目、每个目录
项目	--scope project	.mcp.json，提交到仓库	任何检出该仓库的人
本地	无（默认）	每个目录的用户状态	添加服务时所在的目录

运行 claude mcp list 确认；如果在无关目录中看不到 render，请使用 --scope user 重新运行命令。

Claude Code，以插件形式安装 — 一步即可配置服务及其文档，而且插件默认全局安装：

/plugin marketplace add LuSrodri/render-useful-mcp
/plugin install render-useful-mcp@lusrodri-render

在启动 Claude Code 的 shell 中导出 RENDER_API_KEY；插件会从环境变量中读取它，而不会将其存储起来。请参阅 plugin/README.md。

Claude for macOS 和 Windows，以桌面扩展形式安装 — 从最新版本下载 .mcpb 包并打开。Claude 会安装它，并通过表单询问 API 密钥，因此无需手动配置。该包自带依赖项，不需要 npm 或全局 Node 安装。

桌面安装默认启用 services、logs 和 env-groups 工具集，而非整个目录，因为每个工具定义都会占用每次对话的上下文。将 Toolsets 字段设为 all 或任意逗号分隔的列表即可更改。

除桌面扩展外，所有安装方式都需要 Node.js ≥ 20.11。

npm install -g render-useful-mcp

或者无需安装即可运行，这是大多数 MCP 客户端配置采用的方式：

npx -y render-useful-mcp

它也已列入 MCP Registry，名称为 io.github.LuSrodri/render-useful-mcp，因此可以浏览 Registry 的客户端能够找到并配置它，无需手动指定 npm 包。

配置 MCP 客户端

从 Render Dashboard → Account Settings → API Keys 获取 API 密钥。

Claude Code — 按上述方法进行全局配置：

claude mcp add render --scope user -e RENDER_API_KEY=rnd_your_key -- npx -y render-useful-mcp

如果知道 RENDER_WORKSPACE_ID，也可用相同方式添加：

claude mcp add render --scope user \
  -e RENDER_API_KEY=rnd_your_key \
  -e RENDER_WORKSPACE_ID=tea_your_workspace_id \
  -- npx -y render-useful-mcp

Claude Desktop / 使用 mcpServers 的任意客户端 — 添加到配置文件中：

{
  "mcpServers": {
    "render": {
      "command": "npx",
      "args": ["-y", "render-useful-mcp"],
      "env": {
        "RENDER_API_KEY": "rnd_your_key_here",
        "RENDER_WORKSPACE_ID": "tea_your_workspace_id"
      }
    }
  }
}

RENDER_WORKSPACE_ID 是可选的，但建议设置：许多 Render 端点需要一个模型无法猜出的 ownerId，设置该值可以省去几乎每次会话中的一次查询。可通过 render_list_owners 工具查找，或从控制面板 URL 中读取。

配置

变量	默认值	描述
RENDER_API_KEY	—	必填。 你的 Render API 密钥。
RENDER_WORKSPACE_ID	—	在需要 ownerId 且未提供时应用的工作区 ID。
RENDER_MCP_TOOLSETS	all	将可用范围限定为以逗号分隔的工具集列表。
RENDER_MCP_READ_ONLY	false	为 true 时，只会公开不会修改数据的（GET）工具。
RENDER_MCP_DYNAMIC_TOOLSETS	true	注册 render_toolsets，用于报告工具集及其状态。
RENDER_MCP_TIMEOUT_MS	60000	每个请求的超时时间。
RENDER_MCP_MAX_RETRIES	3	遇到速率限制和临时服务端错误时的重试次数。
RENDER_MCP_MAX_RESPONSE_BYTES	400000	超过此大小的工具结果会被截断并附带说明。
RENDER_MCP_LOG_LEVEL	info	debug、info、warn、error、silent。日志输出到 stderr。
RENDER_API_BASE_URL	https://api.render.com/v1	用于代理或测试的覆盖值。

工具集

默认启用全部 17 个工具集 — 服务会公开 API 密钥允许访问的所有内容。工具集用于有意_缩小_可用范围，而不是需要解锁的门槛。

工具集	工具	涵盖内容
services	43	服务、部署、自定义域名、一次性任务、定时任务运行和事件
metrics	23	CPU、内存、带宽、HTTP、磁盘和连接指标，以及指标流
postgres	21	Postgres 实例、用户、导出、恢复和查询洞察
workflows	15	Render 工作流和工作流任务
env-groups	13	环境组、其变量和密钥文件
projects	12	项目和环境
webhooks	11	Webhook 和通知设置/覆盖
logs	10	日志查询、标签发现和日志流配置
static-sites	9	静态站点的标头规则和重定向/重写路由
deprecated	8	Render 已用 Key Value API 取代的旧版 Redis 端点
key-value	8	Key Value（兼容 Redis）实例和连接信息
workspaces	8	工作区、成员、已验证身份的用户和审计日志
disks	7	持久磁盘及其快照
blueprints	6	Blueprint 和 Blueprint 同步
network	5	专用出站 IP 集
registry	5	容器注册表凭据
maintenance	4	计划的维护运行

你可能仍然想缩小范围的原因：

// A client that struggles with the full catalogue, or a session scoped to one job.
"env": { "RENDER_MCP_TOOLSETS": "services,logs,metrics" }

// An agent that should be able to look but not touch.
"env": { "RENDER_MCP_READ_ONLY": "true" }

如果你确实缩小了范围，模型仍可调用 render_toolsets，查看所有现有工具集以及哪些组已关闭，从而准确告知你需要更改什么。扩大可用范围意味着编辑 RENDER_MCP_TOOLSETS 并重启服务：协议修订版本 2026-07-28 要求 tools/list 的结果不会因连接不同或其他调用的副作用而变化，因此启用的工具集在启动时即固定。

工具

工作流工具

这些工具在任何工具集配置下始终可用。之所以提供这些工具，是因为模型通常无法一次就正确完成相应的原始调用序列。

工具	功能说明
render_find_service	将服务名称（包括部分名称或近似名称）解析为单个 Render 服务，并返回其 ID 和相近的替代项。
render_recent_logs	获取服务的近期日志行，并代为解析服务名称和工作区 ID。
render_service_status	一次调用即可排查服务问题：查看其配置、最新部署、运行中的实例和最近的错误级日志。
render_toolsets	列出所有 Render 工具集、各自的工具数量以及当前是否已启用。
render_wait_for_deploy	轮询部署，直到其达到终止状态（live、build_failed、update_failed、canceled、deactivated）或超时。

API 工具

每个 Render 端点对应一个工具，名称为 render_<operation_id>，例如 render_list_services、render_create_deploy、render_update_postgres 等。每个工具均直接采用 Render 规范中的摘要、描述、参数文档、枚举值和约束。完整列表请参阅工具目录页面。

让模型能够使用这些工具

生成的工具好不好，取决于规范对它的描述，而 Render 的规范描述的是结构，而非用法。以下三点弥补了这一差距：

oneOf 分支会保留名称，并说明适用条件。 解除 $ref 引用通常会丢掉架构名称，导致 render_create_service 上的 serviceDetails 变成五个结构相似的匿名对象，无法说明哪个对象对应哪个 type。现在，每个分支都会将 Render 规范中的名称作为 title 保留下来，因此 cron_job → cronJobDetailsPOST 和 runtime: docker → dockerDetails 就成了模型实际可以做出的判断。

给分支命名让选择变得清晰可读，但无法验证；而 Render 的规范没有 discriminator：按照 oneOf 的恰好匹配一个规则，一个无需任何必填字段的分支——staticSiteDetailsPOST——会接受所有载荷，导致其他四个分支都无法触达。src/tools/schema-unions.ts 会将这些联合类型改写为以选择它们的属性为条件的 if/then 规则，使映射成为架构的一部分，而不是描述中的建议；填错分支的字段会按名称被拒绝，而不会显示 must match exactly one schema in oneOf。如果任何 oneOf 分支无法触达，构建不变量检查就会让生成器失败；test/payloads.test.ts 会针对全部 208 个工具，用真实载荷检查该属性。

移除调用方无法填写的字段。 Render 的规范在少数请求体中复用了响应架构，因此带入了由服务端生成的值：cron job 的 Docker 分支要求提供完整的 registryCredential 对象，其中必须包含凭证的 id 和最后更改时间戳；而 Web 服务只需要一个普通的 registryCredentialId。只能靠编造值填写的字段还不如没有字段，因此 src/tools/schema-repairs.ts 会将其移除，并在用法说明中指向 image.registryCredentialId，这是 Render 实际获取该引用的位置。如果某项不再匹配，生成器就会报错，因此上游修复会触发构建失败。

少数工具附带手写用法说明。 src/tools/operation-hints.ts 会为模型经证明确实容易用错的操作追加一个 Usage: 段落——create-service 提供完整的示例，update-env-vars-for-service 会提醒它会替换整组变量，post-job 则说明它_不能_用于创建 cron job。示例是数据，而非说明文字：测试套件会根据各自工具的架构验证每个示例，并从同一对象生成描述，因此已发布的示例可以证明是服务端接受的。如果某条提示所指的操作已被 Render 撤销，生成器就会报错，因此文件不会悄无声息地过时。

服务端会发送 instructions。 src/instructions.ts 会在 initialize 时发送一次：ID 前缀、先解析名称、哪个工作流工具可替代哪些原始调用序列，以及 oneOf 约定。跨工具建议应放在这里，而不是重复写进每个需要它的工具描述中。

创建一个运行 Docker 镜像的 cron job

这正是促成上述三点的案例。cron job 是一种服务，因此：

// render_create_service
{
  "type": "cron_job",
  "name": "nightly-report",
  "ownerId": "tea-…",
  "repo": "https://github.com/acme/reports",
  "branch": "main",
  "serviceDetails": {
    // the cronJobDetailsPOST branch
    "runtime": "docker",
    "schedule": "0 3 * * *", // five-field cron, UTC, required for cron jobs
    "plan": "starter",
    "region": "oregon",
    "envSpecificDetails": {
      // the dockerDetails branch, because runtime is docker
      "dockerfilePath": "./Dockerfile",
      "dockerContext": ".",
      "dockerCommand": "python report.py",
    },
  },
}

如果要使用预构建镜像而非构建产物，请移除 repo/branch，将 image 设为 {"ownerId": "tea-…", "imagePath": "docker.io/acme/reports:latest"}，使用 "runtime": "image"，并且只在 envSpecificDetails 中提供 dockerCommand。之后可使用 render_update_service 更改计划；使用 render_run_cron_job 触发计划外运行。render_create_job 是另一回事——它是在现有服务上运行一次性命令。

设计说明

自动生成，而非手工编写。 scripts/generate-operations.ts 会读取 spec/render-openapi.json 并生成工具目录。它采用严格校验：未映射的标签、名称冲突、循环 $ref、模板中缺少路径参数，或会覆盖查询参数的请求体属性，都会导致构建失败，而不是生成存在细微错误的工具。升级到新版 Render API 的步骤是：放入新规范，运行 npm run generate，然后检查差异。

架构完整传递给客户端。 Render 的规范使用了完整的 JSON Schema 功能。工具架构会完整解引用并传递，Ajv 会据此校验参数，因此枚举、模式、格式和 oneOf 都会实际生效。这也是服务使用 SDK 的低级 Server，而非只接受 Zod 架构的 McpServer 的原因。唯一有意进行的重写，是上文所述的未指定判别字段的联合类型：如果保持规范中的原样，它们将完全无法满足。

请求体会被扁平化。 请求体属性会变成顶层工具参数，从而让调用点保持简洁，并提高工具调用准确率。生成器会在构建时验证请求体属性不会与路径或查询参数冲突。六个值为数组或 oneOf 的请求体会保留其结构，并置于单个 body 参数下。

错误信息便于采取行动。 失败时会返回 HTTP 状态码、Render 自身的消息，以及针对实际原因的提示——例如，404 会建议通过列表调用确认 id，401 则会指向 API 密钥页面。已注册但处于隐藏状态的工具会说明需要启用哪个工具集，而不是只显示“未知工具”。

重试策略保守。 对速率限制和临时 5xx 错误，会采用去相关抖动退避策略进行重试，并遵守 Retry-After。服务器错误不会触发对非幂等方法的重放：重试 POST /deploys 会导致部署两次。

日志中不会泄露密钥。 日志采用 stderr 上的结构化 JSON 格式——stdout 用于传输——并会对连接字符串、API 密钥和令牌进行脱敏。

开发

npm install
npm run generate    # rebuild the tool catalogue from the OpenAPI spec
npm run docs        # re-render every doc that quotes the catalogue
npm run build
npm test
npm run check       # generate + docs + lint + typecheck + test

文档也会自动生成

工具数量、工具集表格、工作流工具列表、整个 文档站点、llms.txt 和 llms-full.txt 均由 scripts/generate-docs.ts 根据 src/generated/operations.json 生成。本文件和 plugin/README.md 中 `` 标记之间的区域会被原位重写；站点的文件则会整体写入。

npm run docs:check 会重新渲染所有内容，并在结果与已提交内容不一致时失败。 CI 会在每个拉取请求上运行该检查，Pages 工作流会在部署前运行它，而规范同步则会运行 npm run docs，确保 API 变更及相关说明一同出现在一个便于审核的拉取请求中。文档中的数字不会再悄然偏离目录——在此机制建立之前，它们曾经如此。

测试套件涵盖目录不变量（全部 208 个操作、无悬空 $ref、路径参数必填、注释与 HTTP 语义一致）、请求映射、重试和分页行为、组合工具，以及完整的内存 MCP 客户端/服务往返测试。

构建桌面扩展

npm run build:mcpb   # -> build/render-useful-mcp-<version>.mcpb

此命令会将 dist/ 和生产依赖树暂存到 build/mcpb/，然后打包。该捆绑包按设计是自包含的——Claude 无需安装步骤即可运行它——因此依赖项会从此仓库的 node_modules 复制，而不是重新安装，从而确保制品包含测试套件实际运行时使用的依赖树。

仓库根目录中的 manifest.json 是扩展的清单；npm version 会使其版本与软件包保持同步。查看构建好的捆绑包：

npx mcpb info build/render-useful-mcp-<version>.mcpb
npx mcpb unpack build/render-useful-mcp-<version>.mcpb /tmp/check

更新到新的 Render API 版本

此过程已自动化。.github/workflows/spec-sync.yml 每天运行一次，获取 Render 当前的 API 描述，重新生成目录 和文档，并在工具集合实际发生变化时创建拉取请求，同时总结新增、移除或形状发生变化的工具，并在存在破坏性变更时发出警告。不会自动合并任何内容。

每次运行都会写入作业摘要，包括未发现任何变化的运行，因此无需根据是否出现拉取请求来推断，可以直接在 Actions 选项卡中查看“今天检查了吗？”

此计划中的两个细节都是刻意设计的，而且都源于作业看起来已停止运行、实际上却仍在工作：

• 47 5 * * *，而不是 0 6 * * 1。 GitHub 会尽力安排计划工作流，并可能在负载较高时跳过它们；整点是竞争最激烈的时段。曾有一次观察到的计划运行晚了将近 4 小时才启动。每天在一个不起眼的分钟运行，这样即使某次运行被跳过，最多也只会耽误一天，而不是两周；如果运行发现目录没有变化，就会提前退出，因此每天运行只会多消耗几秒 CI 时间。
• .github/spec-sync-heartbeat.json。 如果仓库连续 60 天没有活动，GitHub 会停用其中的计划工作流；停用的工作流无法自行重新启用。当该文件记录的时间戳距今超过 20 天时，工作流会提交一个新时间戳——每年大约 18 次提交，既能让时间间隔远低于限制，也能在 git 日志中留下可见记录，证明例行任务仍在运行。

如需手动执行，或立即检查：

npm run sync-spec   # fetch the current spec into spec/render-openapi.json
npm run generate    # rebuild the catalogue from it
git diff src/generated/operations.json
npm test

Render 不会通过稳定的 URL 提供其 OpenAPI 文档——文档中提到的 .json 和 .yaml 端点均返回 404——因此 scripts/fetch-spec.ts 会从文档 HTML 中提取文档内容。此方法本质上不够稳定，所以脚本会验证提取的内容（标题、服务端、最少操作数），并在验证失败时明确报错，而不是用截断的内容覆盖有效规范。如果 Render 更改其文档平台，同步工作流会运行失败，而不会悄无声息地一直报告“没有变化”。

生成器不会输出无法完全理解的目录——未映射的标签、名称冲突、循环 $ref、模板中缺少的路径参数，或会与查询参数冲突的请求体属性，都会导致构建失败。CI 还会验证已提交的目录是否与规范生成的内容一致，因此未重新生成的规范更新无法合并。

发布

一次发布会将软件包发布到两个位置：npm，以及描述该软件包的元数据发布到 MCP Registry。两者都使用工作流的 GitHub OIDC 令牌进行身份验证——npm 使用 Trusted Publishing，Registry 使用 mcp-publisher login github-oidc——因此任何地方都不会存储 npm 令牌或 Registry 密钥。 npm 发布还会附带来源证明。

npm version patch    # or minor / major
git push --follow-tags

推送 v* 标签会运行 .github/workflows/publish.yml，验证标签与 package.json 一致，并确认生成的目录和文档都是最新的，确定两个目标中哪些仍需发布此版本，然后执行 lint、类型检查、测试、构建和发布。它还会构建 .mcpb 包并将其附加到 GitHub Release；桌面扩展仅通过此处分发。

文档检查在此处再次执行，而不是交由 CI 处理，因为 README.md 会随 npm tarball 一同发布，而且标签可以从任何提交创建。npm 版本不可变，因此，若软件包中的 README 与其旁边的目录内容相矛盾，就无法撤回该软件包。

发布顺序固定：先发布到 npm，再发布到 Registry。Registry 会通过获取已发布的 tarball 并在其 package.json 中查找 mcpName 来验证你是否拥有该软件包，因此在 npm 尚未提供某个版本前，它无法接受该版本。

如果发布因代码之外的原因失败，请在 Actions 选项卡中点击 Run workflow 重新运行，并在 Use workflow from 下选择对应标签。两个目标会分别检查，因此半途完成发布后重试时，已成功的目标会被跳过，不会因 npm 版本不可变而失败。工作流会拒绝从分支触发的运行，因此已发布的版本始终对应一个标签。

Registry 清单

server.json 是 Registry 中此服务的元数据副本。它的两个字段至关重要，test/server-json.test.ts 会对两者进行断言：

• name 必须是 io.github.LuSrodri/...。Registry 会根据 OIDC 令牌的 repository_owner 声明确定你可以发布到的命名空间，并区分大小写进行比较，因此小写拼写会被拒绝并返回 403。
• package.json 中的 mcpName 必须与该名称一致。这是上文所述的所有权证明；没有它，Registry 会拒绝此软件包。

版本字段与 package.json 保持一致——npm version 会通过 version 生命周期脚本同步它们，因此从干净的本地检出运行 mcp-publisher publish 也能正常工作。CI 会在发布前再次从标签写入这些字段，因此最终发布内容由标签决定。

隐私

没有遥测、没有分析、没有后端。服务在你的计算机上运行，只会连接一个主机：Render 的 API。你的密钥从环境中读取，只发送给 Render，绝不会写入磁盘，并且会从日志输出中隐藏。完整详情（包括如何自行验证每项声明）：PRIVACY.md。

许可证

MIT——参见 LICENSE。

与 Render 无关联。spec/render-openapi.json 是 Render 发布的 API 描述文件，随项目一并提供，以确保构建可复现。