Octopus Deploy Official MCP Server

[!WARNING] 已弃用： 此 MCP 服务器已弃用。远程 MCP 服务器在 Octopus Server 2026.3 及更高版本中可用。请参阅 远程 MCP 服务器文档。

Octopus Deploy Official MCP Server

Octopus 让您轻松地将软件交付到 Kubernetes、多云、本地基础设施以及任何其他环境。通过一款能够以其他工具无法比拟的方式处理大规模 CD 的工具，自动化您的软件和 AI 工作负载的发布、部署和运维。

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

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

Octopus Server 兼容性

MCP Server 公开的大多数工具都使用稳定的 API，这些 API 至少从 Octopus Server 的 2021.1 版本开始就可用。较新的工具将在文档中指定最低支持版本。或者，您可以使用命令行参数 --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
• MCP 服务器可通过 HTTPS 访问的 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 Server 通常在您选择的 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 Server 支持多个命令行选项，用于自定义哪些工具可用。

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

工具集

使用 --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 方法强制执行（代理无法通过谎报意图来绕过）：

• read — 始终允许。通过 execute 的 GET 请求，以及所有 find_* / get_* / list_* 工具。
• write — 通过 execute 的 POST/PUT/PATCH 以及上述始终写入工具。当设置 --read-only 时被阻止。
• delete — 通过 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 Server 版本并退出

🔨 工具

基于 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：搜索 Octopus API 目录（octopus://api/llms.txt），采用 grep 风格语义（最低支持的 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 被阻止；否则需要通过引导（elicitation）获得用户确认。
  • DELETE 需要 --allow-deletes（并在设置 --read-only 时被阻止），外加更强的“不可逆（IRREVERSIBLE）”引导消息。
  • 即使两个标志都开启，敏感拒绝列表（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）会使其路径即使在 GET 下也无法通过 execute 访问。

目录数据也以 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 兜底工具）获取完整发布主体，包括发布说明和所选包。

运行手册

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

完整运行手册主体（包括运行时策略字段）可作为 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、可选的 before/after 上下文数组，以及整个日志中的 totalMatches 计数。

有意不提供 /log 资源：活动日志可能达到数 MB，可寻址资源会诱使调用者获取整个主体，而 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} 资源以获取完整 Form 定义（控件类型、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 Server 包含读和写操作。重要的安全注意事项：

读操作

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

写操作

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

• 创建发布：可为项目创建新发布
• 部署发布：可触发对环境（包括生产环境）的部署
• 运行运行手册：可对环境租户执行运行手册
• 更新功能开关：可切换各环境状态并更改现有开关的推出百分比
• 通过 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 客户端目前不支持链式工具调用（将一个工具的输出用作下一个工具的输入），而是退化为逐 token 复制结果，这经常导致幻觉。如果您希望处理 Octopus 实例中的历史数据以进行分析，我们建议直接使用 API，或编写自己的、能够以编程方式处理工具调用结果的 MCP 客户端。

性能

MCP Server 本质上只是现有 Octopus Server API 之上的一层薄封装。因此，它能够检索大量数据（例如，请求数千个部署）。此类查询可能对实例性能产生显著影响。请指示您的模型仅检索所需的最小数据集（大多数模型开箱即用就能很好地做到这一点）。

🤝 贡献

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

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

请使用问题反馈提供反馈或请求功能。

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

🙋 常见问题解答

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

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

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

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

许可证

本项目根据 Mozilla Public License 2.0 开源许可证的条款进行许可。