Octopus Deploy Official MCP Server

官方

Octopus MCP Server 为您的 AI 助手提供强大工具，使其能够检查、查询和诊断 Octopus 实例中的问题，将其转变为您的终极 DevOps 搭档。

GitHub
98

文档

Octopus Deploy Logo

Octopus Deploy 官方 MCP 服务器

Octopus 让向 Kubernetes、多云、本地基础设施以及任何其他地方交付软件变得简单。借助一款能够以其他工具无法比拟的方式大规模处理持续交付的工具，自动化您的软件和 AI 工作负载的发布、部署与运维。

模型上下文协议（MCP）允许您日常使用的 AI 助手（如 Claude Code 或 ChatGPT）以标准化的方式连接到您拥有的系统和服务，使它们能够从这些系统和服务中提取信息来回答问题并执行任务。

Octopus MCP 服务器为您的 AI 助手提供了强大的工具，使其能够检查、查询和诊断 Octopus 实例中的问题，将其转变为您的终极 DevOps 搭档。有关支持的使用场景和示例提示，请参阅我们的文档。

Octopus 服务器兼容性

MCP 服务器暴露的大多数工具使用至少从 Octopus 服务器 2021.1 版本起就已可用的稳定 API。较新的工具将在文档中注明最低支持的版本。或者，您可以使用命令行参数 --list-tools-by-version 来检查特定工具与 Octopus 版本的关系。

🚀 安装

通过 Docker 安装

必须通过环境变量提供凭据，以避免在主机进程列表中暴露它们（ps aux / /proc/<pid>/cmdline）。Octopus 服务器 URL 仍可通过 --server-url 标志提供。

docker run -i --rm -e OCTOPUS_API_KEY=your-key -e OCTOPUS_SERVER_URL=https://your-octopus.com octopusdeploy/mcp-server

完整配置示例（适用于 Claude Desktop、Claude Code 和 Cursor）：

{
  "mcpServers": {
    "octopus-deploy": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OCTOPUS_SERVER_URL",
        "-e",
        "OCTOPUS_API_KEY",
        "octopusdeploy/mcp-server"
      ],
      "env": {
        "OCTOPUS_SERVER_URL": "https://your-octopus.com",
        "OCTOPUS_API_KEY": "YOUR_API_KEY"
      }
    },
  }
}

对于 Apple Mac 用户，您可能需要在配置中添加以下参数，以强制 Docker 使用 Linux 平台：

"--platform",
"linux/amd64",

我们计划很快发布原生 ARM 构建版本，届时将不再需要这些参数。

通过 Node 安装

要求

  • Node.js >= v20.0.0
  • 可通过 HTTPS 被 MCP 服务器访问的 Octopus Deploy 实例
  • Octopus Deploy API 密钥或访问令牌（请参阅下方的身份验证）

配置

完整配置示例（适用于 Claude Desktop、Claude Code 和 Cursor）：

启用写入工具（默认）：

{
  "mcpServers": {
    "octopusdeploy": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@octopusdeploy/mcp-server"],
      "env": {
        "OCTOPUS_SERVER_URL": "https://your-octopus.com",
        "OCTOPUS_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

只读模式（推荐用于生产环境）：

{
  "mcpServers": {
    "octopusdeploy": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@octopusdeploy/mcp-server", "--read-only"],
      "env": {
        "OCTOPUS_SERVER_URL": "https://your-octopus.com",
        "OCTOPUS_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Octopus MCP 服务器通常在您选择的 AI 客户端中进行配置。

它以 npm 包的形式打包，并通过 Node 的 npx 命令执行。凭据（API 密钥或访问令牌）必须通过环境变量提供——它们不作为命令行参数接受，以避免在进程列表中暴露机密信息。Octopus 服务器 URL 可以通过 OCTOPUS_SERVER_URL 环境变量或 --server-url 标志提供。

OCTOPUS_API_KEY=API-KEY \
OCTOPUS_SERVER_URL=https://your-octopus.com \
npx -y @octopusdeploy/mcp-server

或者在命令行中指定服务器 URL：

OCTOPUS_API_KEY=API-KEY \
npx -y @octopusdeploy/mcp-server --server-url https://your-octopus.com

身份验证

MCP 服务器支持两种身份验证方法。两者都通过环境变量提供——凭据不在命令行上接受，因为标志对任何本地用户都在主机进程列表中可见。

API 密钥（推荐用于交互式使用）

API 密钥是 Octopus Deploy 的标准身份验证方法。您可以从 Octopus Deploy 用户个人资料中生成一个。

OCTOPUS_API_KEY=API-XXXXXXXXXXXXXXXXXXXXXXXXXX \
OCTOPUS_SERVER_URL=https://your-octopus.com \
npx -y @octopusdeploy/mcp-server

访问令牌 / Bearer 令牌（仅限自动化场景）

服务器还支持短期访问令牌（Bearer 令牌）作为 API 密钥的替代方案。此身份验证方法仅适用于自动化场景，即外部系统向 MCP 服务器颁发短期令牌（例如，CI/CD 流水线、自动化编排或机器对机器工作流）。不要使用长期 Bearer 令牌——对于交互式或长期运行的会话，请改用 API 密钥。

OCTOPUS_ACCESS_TOKEN=your-short-lived-token \
OCTOPUS_SERVER_URL=https://your-octopus.com \
npx -y @octopusdeploy/mcp-server

使用访问令牌的完整配置示例：

{
  "mcpServers": {
    "octopusdeploy": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@octopusdeploy/mcp-server"],
      "env": {
        "OCTOPUS_SERVER_URL": "https://your-octopus.com",
        "OCTOPUS_ACCESS_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

如果同时提供了 API 密钥和访问令牌，则访问令牌优先。活动身份验证方法会记录在日志文件中（可通过 --log-file 配置），以便运维人员确认正在使用哪个凭据。

配置选项

Octopus MCP 服务器支持多个命令行选项，用于自定义可用的工具。

如果您不确定需要哪些工具，我们建议在不添加任何额外命令行选项的情况下运行，并使用提供的默认设置。

工具集

使用 --toolsets 参数来启用特定的工具组：

# Enable all toolsets (default)
npx -y @octopusdeploy/mcp-server

# Enable only specific toolsets
npx -y @octopusdeploy/mcp-server --toolsets projects,deployments

# Enable all toolsets explicitly
npx -y @octopusdeploy/mcp-server --toolsets all

可用的工具集：

  • core - 基本操作（始终启用）
  • projects - 项目操作
  • deployments - 部署操作
  • releases - 发布管理
  • runbooks - Runbook 发现与执行
  • tasks - 任务操作
  • tenants - 多租户操作
  • kubernetes - Kubernetes 操作
  • machines - 部署目标操作
  • certificates - 证书操作
  • accounts - 账户操作
  • interruptions - 手动干预和审批操作
  • featureToggles - 检查和调整客户功能开关
  • context - 已认证用户和项目上下文（当前用户、Git 分支）

只读模式

服务器默认在启用写入工具的情况下运行。传递 --read-only 可禁用所有写入工具，并通过 execute 后盾阻止 POST/PUT/PATCH/DELETE 请求。大多数精选工具已经是只读的；只有一小部分执行写入操作。

启用写入的工具（始终写入）：

  • create_release - 创建新发布
  • deploy_release - 将发布部署到环境和租户
  • run_runbook - 针对一个或多个环境（以及可选的租户）运行 Runbook
  • update_feature_toggle - 调整现有功能开关的每个环境状态和推出百分比

有条件写入的工具： execute 是一个结构化的 REST 后盾，其层级（读取 / 写入 / 删除）由传递给它的 HTTP 方法决定。详情请参阅 API 目录与后盾 部分。

写入工具受 MCP 启发式提示控制：支持启发式提示的客户端将在调用继续前被要求确认。不支持启发式提示的客户端必须在工具参数中传递 confirm: true——否则工具将中止并报错。设置 OCTOPUS_SKIP_ELICITATION=true 可完全绕过此门控（适用于无人值守的自动化）。

服务器使用三级读取/写入/删除分类，基于 HTTP 方法在服务器端强制执行（代理无法通过谎报意图来绕过）：

  • 读取 — 始终允许。通过 execute 的 GET 请求，以及所有 find_* / get_* / list_* 工具。
  • 写入 — 通过 execute 的 POST/PUT/PATCH 请求以及上述始终写入的工具。当设置 --read-only 时被阻止。
  • 删除 — 通过 execute 的 DELETE 请求。需要 --allow-deletes，并在设置 --read-only 时被阻止。一小部分灾难性删除路径（例如 DELETE /api/spaces/{id}、DELETE /api/users/{id}）和 API 密钥端点位于硬性敏感拒绝列表中，忽略这两个标志。
# Default - write tools enabled (POST/PUT/PATCH)
npx -y @octopusdeploy/mcp-server

# Additionally permit DELETE requests through the execute tool
npx -y @octopusdeploy/mcp-server --allow-deletes

# Read-only mode - write/delete tools disabled
npx -y @octopusdeploy/mcp-server --read-only

安全说明： 使用具有适当、最小权限的 API 密钥——写入操作可以在您的 Octopus 实例中创建发布并触发部署。对于生产环境，请考虑传递 --read-only，除非您有特定、受控的写入用例。--allow-deletes 默认关闭；仅在代理必须通过 execute 发出 DELETE 请求时启用它。如果您同时传递 --allow-deletes 和 --read-only，服务器会向 stderr 打印启动警告——DELETE 请求仍会被只读门控阻止。

完整示例

以下所有示例均假设已在环境中设置 OCTOPUS_API_KEY。为清晰起见，显示了 --server-url 标志，但也可以通过 OCTOPUS_SERVER_URL 提供。

# Development setup with only core and project tools
npx -y @octopusdeploy/mcp-server --toolsets core,projects --server-url https://your-octopus.com

# Production setup with all tools and read-only enforcement
npx -y @octopusdeploy/mcp-server --toolsets all --read-only --server-url https://your-octopus.com

# Default invocation - all tools and writes enabled
npx -y @octopusdeploy/mcp-server --server-url https://your-octopus.com

其他命令行参数

  • --read-only - 启用只读模式：禁用所有精选写入工具，并通过 execute 阻止 POST/PUT/PATCH/DELETE 请求。写入功能默认启用；此标志将其关闭。请参阅只读模式。
  • --allow-deletes - 允许通过 execute 工具发出 DELETE 请求。当设置 --read-only 时被忽略（并发出启动警告）。默认 false。
  • --log-level <level> - 最低日志级别（info、error）
  • --log-file <path> - 日志文件路径或文件名。如果未指定，日志仅写入控制台
  • -q, --quiet - 禁用文件日志记录，仅将错误记录到控制台
  • --list-tools-by-version - 列出所有已注册工具及其支持的 Octopus 服务器版本并退出

🔨 工具

基于 URL 的工具

快速入门：直接粘贴 Octopus URL 来调查问题，无需手动提取 ID。

  • get_deployment_from_url：从部署 URL 获取部署详情（返回 taskId 以供后续使用）
  • get_task_from_url：从任务 URL 获取任务详情和日志

部署调查工作流：

1. get_deployment_from_url with deployment URL
   → Returns deployment context + taskResourceUri + grepTaskLogHint

2a. Fetch the structured activity tree via resources/read (or read_resource)
    octopus://spaces/{spaceName}/tasks/{taskId}/details

2b. Or call grep_task_log with the taskId to search the raw log without
    fetching the full body:
       grep_task_log({ spaceName, taskId, pattern: "error|fail", caseInsensitive: true })

任务调查（直接使用任务 URL）：

get_task_from_url with task URL
→ Returns task details and logs immediately

这些工具通过以下方式消除了手动提取 ID 的需要：

  • 自动解析 URL
  • 将空间 ID 解析为空间名称
  • 验证 ID 格式
  • 提供清晰的错误消息

示例 URL：

  • 部署：https://your-octopus.com/app#/Spaces-1/projects/my-app/deployments/Deployments-123
  • 任务：https://your-octopus.com/app#/Spaces-1/tasks/ServerTasks-456

有关详细的工作流、示例和最佳实践，请参阅使用 URL。

核心工具

  • list_spaces：列出 Octopus Deploy 实例中的所有空间
  • list_environments：列出给定空间中的所有环境

API 目录与后盾

这些工具和资源允许代理访问没有专用精选工具的 Octopus REST 端点，并在服务器端对读取、写入和删除操作进行严格的门控。

  • grep_llms_txt：使用 grep 风格的语义搜索 Octopus API 目录（octopus://api/llms.txt）（最低支持的 Octopus 版本：2026.2.3916）。目录正文很大（通常超过 300 KB）——请调用此工具，而不是直接读取资源正文。参数与 GNU grep 对应（pattern、caseInsensitive、invertMatch、fixedString、beforeContext、afterContext、maxCount）。适用于发现端点（POST /releases）、枚举删除端点（DELETE ）或查找写入操作的正文类型（Body: Create.*Command）。
  • execute：结构化的 REST 后备工具。可访问 /api 下的任何 Octopus REST 端点。HTTP 方法是权威的读/写/删除分类器——绝不是 LLM 可以设置的 isWrite 标志。方法门控在服务器端硬编码：
    • GET 始终允许（受路径形状检查 + 敏感拒绝列表约束）。
    • 当 --read-only 设置时，POST/PUT/PATCH 被阻止；否则需要通过引导获得用户确认。
    • DELETE 需要 --allow-deletes（并且当 --read-only 设置时被阻止），外加更强的“不可逆”引导消息。
    • 敏感拒绝列表（API 密钥端点、DELETE /api/spaces/{id}、DELETE /api/users/{id}）即使两个标志都开启也会强制执行。
    • 路径必须是 /api 或以 /api/ 开头——绝对 URL、SDK 相对的 ~/api/... 路径以及 /api 之外的主机相对路径（例如 /octopus/portal/...）会被预先拒绝，因此 execute 始终限定在 Octopus REST API 表面内。
    • 每个工具集的路径允许列表仅在 --toolsets 被缩小时适用。 当所有工具集都启用时（默认，或显式 --toolsets all），允许列表被绕过，/api 下的任何路径均可访问，但需遵守上述门控。当 --toolsets 被缩小时，允许列表成为终止开关：路径仅在其所属工具集启用时才解析，因此禁用某个工具集（例如 certificates）会使其路径即使通过 execute 在 GET 上也无法访问。

目录数据也作为 MCP 资源公开：

  • octopus://api/llms.txt — 每个 Octopus REST 端点的 Markdown 目录（HTTP 方法、路径、查询参数、请求/响应类型）。需要 Octopus Server 2026.2.3916 或更高版本。基于配置的服务器 URL 进行 5 分钟内存缓存。优先使用 grep_llms_txt，而不是直接读取正文。
  • octopus://api/capabilities — 描述当前运行会话的 JSON：服务器版本、启用的工具集、可用工具（及其 minimumOctopusVersion），以及 --read-only / --allow-deletes 是否开启。有助于代理发现此会话中可访问的内容。

项目

  • list_projects：列出给定空间中的所有项目

部署

  • deploy_release：将版本部署到环境（支持租户和非租户部署）
  • list_deployments：列出空间中的部署，支持可选过滤

版本

  • create_release：为项目创建新版本
  • find_releases：在空间中查找版本（可按 ID 获取特定版本，或按项目列出/过滤版本）

版本详情也可作为 MCP 资源在 octopus://spaces/{spaceName}/releases/{releaseId} 获取——通过 resources/read（或 read_resource 后备工具）获取完整的版本正文，包括版本说明和选定的包。

Runbook

  • find_runbooks：在项目中查找 Runbook（可按 ID 获取特定 Runbook，或按部分名称列出/过滤 Runbook）。每个摘要包含已发布的快照 ID、多租户模式和环境范围，以便调用者在运行前选择有效目标。
  • run_runbook：针对一个或多个环境运行 Runbook。支持租户运行（按租户名称或租户标签）、提示变量、引导失败模式、计划运行窗口以及步骤或机器包含/排除。如果省略 runbookSnapshotId，则默认使用 Runbook 的已发布快照。

完整的 Runbook 正文（包括运行时策略字段）作为 MCP 资源在 octopus://spaces/{spaceName}/runbooks/{runbookId} 提供。

任务

任务数据主要作为 MCP 资源公开。使用 resources/read（或 read_resource 后备工具）配合以下之一：

  • octopus://spaces/{spaceName}/tasks/{taskId} — 轻量级元数据（状态、时间、完成标志）
  • octopus://spaces/{spaceName}/tasks/{taskId}/details — 完整的 ServerTaskDetails（进度、ActivityLogs 树等）

对于日志搜索，请使用 grep_task_log 工具，而不是 /log 资源：

  • grep_task_log：搜索任务的活动日志，无需获取完整正文。参数与 GNU grep 对应（pattern、caseInsensitive、invertMatch、fixedString、beforeContext、afterContext、maxCount）。返回匹配行，包含从 1 开始的 lineNumber、可选的前后上下文数组，以及整个日志中的 totalMatches 计数。

有意不提供 /log 资源：活动日志可能达到数兆字节，可寻址资源会诱使调用者获取整个正文，而 grep 几乎总是正确的原语。

租户

  • find_tenants：在空间中查找租户（可按 ID 获取特定租户，或使用过滤器列出/搜索租户）
  • get_tenant_variables：按类型获取租户变量（全部、公共或项目）
  • get_missing_tenant_variables：获取缺少值的租户变量

Kubernetes

  • get_kubernetes_live_status：获取项目和环境的 Kubernetes 资源实时状态（最低支持版本：2025.3）

机器（部署目标）

  • find_deployment_targets：在空间中查找部署目标（可按 ID 获取特定目标，或使用过滤器列出/搜索目标）

证书

  • find_certificates：在空间中查找证书（可按 ID 获取特定证书，或使用过滤器列出/搜索证书）

账户

  • find_accounts：在空间中查找账户（可按 ID 获取特定账户，或使用过滤器列出/搜索账户）

中断

  • find_interruptions：查找空间中待处理或历史中断（手动干预、审批、引导失败提示），可按任务、项目、环境、相关文档、责任人或待处理状态进行过滤。返回精简摘要；解引用 octopus://spaces/{spaceName}/interruptions/{interruptionId} 资源以获取完整的表单定义（控件类型、Markdown 说明、按钮选项、提交的 Form.Values）。

功能开关

  • find_feature_toggles：列出项目中的客户功能开关。每个摘要包含每个环境的状态（isEnabled、rolloutPercentage、clientRolloutPercentage）以及 resourceUri，因此“X 在哪里开启”可以从列表响应中回答。
  • update_feature_toggle：调整现有开关。操作面较窄——翻转某个环境的开启/关闭状态、更改推出百分比，或更新开关级别的描述/默认状态。内部获取当前开关，在内存中应用您的补丁，并 PUT 合并后的正文，因此未提及的环境和未提及的字段将被保留。引用开关上尚未配置的环境的补丁将被拒绝。

完整的开关正文（描述、租户、分段、最低版本）作为 MCP 资源在 octopus://spaces/{spaceName}/projects/{projectId}/featuretoggles/{slug} 提供。推出组正文可在 octopus://spaces/{spaceName}/projects/{projectId}/rolloutgroups/{rolloutGroupId} 寻址，用于只读检查。

超出范围（请使用 Octopus UI）： 创建新功能开关、删除开关、重命名或重新标记、附加/分离推出组、租户定位、分段、最低版本过滤器以及推出组/SDK 客户端标识符管理。

其他工具

  • get_deployment_process：按 ID 获取项目或版本的部署过程
  • get_variables：获取项目的所有项目变量和库变量集变量（通过 gitRef 支持配置即代码项目）
  • get_branches：获取版本控制项目的 Git 分支（最低支持版本：2021.2）
  • get_current_user：获取当前已认证用户的信息

🔒 安全注意事项

Octopus MCP 服务器包含读取和写入操作。重要的安全注意事项：

读取操作

  • 可以读取完整的部署日志，如果日志中的机密未标记为机密，则可能包含生产机密
  • 访问敏感的配置数据和变量
  • 在连接到您不完全信任的工具和模型时请谨慎行事

写入操作

默认情况下，以下写入操作可用：

  • 创建版本：可以为项目创建新版本
  • 部署版本：可以触发部署到环境（包括生产环境）
  • 运行 Runbook：可以针对环境和租户执行 Runbook
  • 更新功能开关：可以翻转每个环境的状态并更改现有开关的推出百分比
  • 通过 execute 后备工具进行任意 POST/PUT/PATCH：限定在 /api 下的路径，并始终启用敏感拒绝列表。每个工具集的路径允许列表仅在 --toolsets 被缩小时适用；当所有工具集都启用时（默认），唯一的路径门控是 /api 边界和敏感拒绝列表。

传递 --read-only 以禁用上述所有操作。通过 execute 发出的 DELETE 请求需要额外的 --allow-deletes 标志——这是对不可逆操作的刻意选择加入——并且在 --read-only 设置时仍会被阻止。

关键安全措施：

  1. 最小权限：使用具有您的用例所需最低权限的 API 密钥
  2. 选择加入只读模式：写入操作默认启用。对于生产环境，请传递 --read-only，除非您有特定的、受控的写入操作用例。DELETE 始终需要额外的 --allow-deletes 选择加入。
  3. 方法门控是服务器端硬编码的：传递给 execute 的 HTTP 方法是权威分类器。代理无法通过歪曲调用的作用来绕过门控——POST/PUT/PATCH/DELETE 请求会获得特定于层级门控，无论请求正文中的描述如何。
  4. 工具集过滤兼作终止开关：缩小 --toolsets 会同时移除已禁用工具集的精选工具及其在 execute 允许列表中的路径。（允许列表仅在工具集被缩小时才被参考；当所有工具集都启用时，execute 受 /api 形状检查和敏感拒绝列表约束。）
  5. 提示注入风险：以完全自动化的方式运行代理可能会使您容易受到提示注入攻击

建议：对于生产环境，请传递 --read-only，除非您有特定的、受控的写入操作用例。除非您特别需要通过 execute 使用 DELETE 语义，否则请保持 --allow-deletes 关闭。

⚠️ 限制

数据分析

当前 AI 聊天工具和 MCP 协议本身的性质使得分析大量数据不切实际。大多数 MCP 客户端目前不支持链式工具调用（将一个工具的输出用作下一个工具的输入），而是退回到逐个令牌复制结果，这经常导致幻觉。如果您希望处理来自 Octopus 实例的历史数据以进行分析，我们建议直接使用 API 或编写自己的 MCP 客户端，该客户端能够以编程方式处理工具调用结果。

性能

MCP 服务器在技术上只是现有 Octopus 服务器 API 之上的一个薄层。因此，它能够检索大量数据（例如，请求数千个部署）。此类查询可能会对实例的性能产生显著影响。请指示您的模型仅检索所需的最少数据集（大多数模型开箱即用地擅长这一点）。

🤝 贡献

欢迎贡献！:heart: 请阅读我们的贡献指南，了解如何参与此项目。

我们非常期待听到您计划如何使用 Octopus MCP Server，以及您希望在未来的版本中看到哪些功能。

请使用 Issues 提供反馈或请求新功能。

如果您是 Octopus 的现有客户，请将使用 MCP 服务器时遇到的任何问题报告给我们的支持团队。这将确保您在我们的标准支持保障范围内得到及时响应。

🙋 常见问题

你们有计划发布远程 MCP 服务器吗？

我们正在努力将 MCP 服务器直接集成到 Octopus Server 中。这将为我们构建更复杂的 MCP 工具打开大门，同时还能：

  • 让 Octopus 管理员对 MCP 客户端进行更精细的控制
  • 原生支持 OAuth 进行客户端身份验证
  • 将安全扫描工具集成到 MCP 输出中

如果您对此感兴趣，请在我们的路线图项目上登记您的意向。

许可证

本项目基于 Mozilla Public License 2.0 开源许可证条款授权。