Octopus Deploy Official Mcp Server

警告

**已弃用：**此 MCP 服务已弃用。Octopus Server 2026.3 及更高版本提供远程 MCP 服务。请参阅远程 MCP 服务文档。

Octopus Deploy 官方 MCP 服务

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

Model Context Protocol（MCP）允许你在日常工作中使用的 AI 助手（如 Claude Code 或 ChatGPT）以标准化方式连接到你拥有的系统和服务，从中获取信息以回答问题并执行任务。

Octopus MCP 服务为你的 AI 助手提供强大的工具，使其能够检查和查询 Octopus 实例，并诊断其中的问题，让它成为你最得力的 DevOps 搭档。有关支持的用例和提示词示例，请参阅我们的文档。

Octopus Server 兼容性

MCP 服务提供的大多数工具使用稳定的 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 Key 或 Access Token（请参阅下文的身份验证）

配置

完整配置示例（适用于 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 key 或 access token）——为避免机密暴露在进程列表中，不接受通过命令行参数提供凭据。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 - 在一个或多个环境（以及可选的租户）中运行运行手册
• update_feature_toggle - 调整现有功能开关的各环境状态和发布百分比

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

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

服务采用三层读取 / 写入 / 删除分类，并根据 HTTP 方法在服务端强制执行（Agent 不能通过谎报意图绕过此机制）：

• 读取 — 始终允许。通过 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 处于关闭状态；只有当 Agent 必须通过 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 目录与后备工具

这些工具和资源可让 Agent 访问没有专用精选工具的 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 方法是读取／写入／删除操作分类的权威依据——绝不使用可由大模型设置的 isWrite 标志。方法限制在服务端硬编码：
  • GET 始终允许（但受路径格式检查和敏感端点拒绝列表限制）。
  • 设置 --read-only 时会阻止 POST／PUT／PATCH；否则必须通过 elicitation 获得用户确认。
  • DELETE 需要设置 --allow-deletes（且设置 --read-only 时会被阻止），并且必须通过更严格的“IRREVERSIBLE” elicitation 消息进行确认。
  • 即使同时启用了这两个标志，敏感端点拒绝列表（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。可用于帮助 Agent 发现当前会话中可访问的内容。

项目

• 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（Progress、ActivityLogs 树等）

搜索日志时，请使用 grep_task_log 工具，而不要使用 /log 资源：

• grep_task_log：搜索任务的活动日志，无需获取完整正文。参数与 GNU grep 类似（pattern、caseInsensitive、invertMatch、fixedString、beforeContext、afterContext、maxCount）。返回匹配行及从 1 开始的 lineNumber、可选的前后文数组，以及整个日志中的 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 时，DELETE 请求仍会被阻止。

关键安全措施：

1. 最小权限：使用具备满足用例所需最低权限的 API 密钥
2. 主动启用只读模式：默认启用写入操作。在生产环境中，除非有特定且受控的写入操作用例，否则请传入 --read-only。DELETE 始终需要额外传入 --allow-deletes 以主动授权。
3. 方法门控在服务端执行且是硬编码的：传入 execute 的 HTTP 方法是权威的分类依据。Agent 无法通过歪曲调用的实际操作来绕过门控——无论请求正文中的文字如何，POST/PUT/PATCH/DELETE 请求都会受到对应级别的门控。
4. 工具集筛选也可用作紧急开关：缩小 --toolsets 范围会同时移除已禁用工具集中的精选工具及其在 execute 允许列表中的路径。（只有在缩小工具集范围时才会检查允许列表；启用所有工具集时，execute 受 /api 格式检查和敏感路径拒绝列表限制。）
5. 提示词注入风险：以完全自动化的方式运行 Agent，可能会使你容易受到提示词注入攻击

建议：在生产环境中，除非有特定且受控的写入操作用例，否则请传入 --read-only。除非确实需要通过 execute 使用 DELETE 语义，否则请勿启用 --allow-deletes。

⚠️ 局限性

数据分析

当前 AI 聊天工具和 MCP 协议本身的特性，使其难以分析大量数据。目前大多数 MCP 客户端不支持链式调用工具（将一个工具的输出用作下一个工具的输入），而是通过逐个令牌复制结果来处理，这往往会导致幻觉。如果你希望处理 Octopus 实例中的历史数据以进行分析，我们建议直接使用 API，或编写自己的 MCP 客户端，以便通过编程方式处理工具调用结果。

性能

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

🤝 贡献

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

我们很想了解你计划如何使用 Octopus MCP Server，以及你希望在未来版本中看到哪些功能。

请通过 Issues 提供反馈或请求功能。

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

🙋 常见问题

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

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

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

如果你对此感兴趣，请在我们的路线图条目中登记意向。

许可证

本项目采用 Mozilla Public License 2.0 开源许可证。