Octopus Deploy Official MCP Server

Octopus makes it easy to deliver software to Kubernetes, multi-cloud, on-prem infrastructure, and anywhere else. Automate the release, deployment, and operations of your software and AI workloads with a tool that can handle CD at scale in ways no other tool can.

Model Context Protocol (MCP) allows the AI assistants you use in your day to day work, like Claude Code, or ChatGPT, to connect to the systems and services you own in a standardized fashion, allowing them to pull information from those systems and services to answer questions and perform tasks.

The Octopus MCP Server provides your AI assistant with powerful tools that allow it to inspect, query, and diagnose problems within your Octopus instance, transforming it into your ultimate DevOps wingmate. For a list of supported use-cases and sample prompts, see our documentation.

Octopus Server Compatibility

Most tools exposed by the MCP Server use stable APIs that have been available from at least version 2021.1 of Octopus Server. Tools that are newer will specify the minimum supported version in the documentation. Alternatively, you can use the command line argument --list-tools-by-version to check how specific tools relate to versions of Octopus.

🚀 Installation

Install via Docker

Credentials must be supplied via environment variables to avoid exposing them in the host process list (ps aux / /proc/<pid>/cmdline). The Octopus server URL can still be supplied via the --server-url flag.

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

Full example configuration (for Claude Desktop, Claude Code, and 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"
      }
    },
  }
}

For Apple Mac users, you might need to add the following arguments in the configuration to force Docker to use the Linux platform:

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

We are planning to release a native ARM build shortly so that those arguments will not be required anymore.

Install via Node

Requirements

• Node.js >= v20.0.0
• Octopus Deploy instance that can be accessed by the MCP server via HTTPS
• Octopus Deploy API Key or Access Token (see Authentication below)

Configuration

Full example configuration (for Claude Desktop, Claude Code, and Cursor):

Write tools enabled (default):

{
  "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"
      }
    }
  }
}

Read-only mode (recommended for production):

{
  "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"
      }
    }
  }
}

The Octopus MCP Server is typically configured within your AI Client of choice.

It is packaged as an npm package and executed via Node's npx command. Credentials (API key or access token) must be supplied via environment variables — they are not accepted as command-line arguments to avoid exposing secrets in the process list. The Octopus server URL may be supplied via either the OCTOPUS_SERVER_URL environment variable or the --server-url flag.

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

Or with the server URL on the command line:

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

Authentication

The MCP server supports two authentication methods. Both are supplied via environment variables — credentials are not accepted on the command line because flags are visible in the host process list to any local user.

API Key (recommended for interactive use)

API keys are the standard authentication method for Octopus Deploy. You can generate one from your Octopus Deploy user profile.

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

Access Token / Bearer Token (automated scenarios only)

The server also supports short-lived access tokens (Bearer tokens) as an alternative to API keys. This authentication method is intended only for automated scenarios where an external system issues a short-lived token to the MCP server (e.g., CI/CD pipelines, automated orchestration, or machine-to-machine workflows). Do not use long-lived Bearer tokens — use API keys instead for interactive or long-running sessions.

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

Full example configuration with an access token:

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

If both an API key and an access token are provided, the access token takes precedence. The active authentication method is recorded in the log file (configurable with --log-file) so operators can confirm which credential is in use.

Configuration Options

The Octopus MCP Server supports several command-line options to customize which tools are available.

If you are not sure which tools you require, we recommend running without any additional command-line options and using the provided defaults.

Toolsets

Use the --toolsets parameter to enable specific groups of tools:

# 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

Available toolsets:

• core - Basic operations (always enabled)
• projects - Project operations
• deployments - Deployment operations
• releases - Release management
• runbooks - Runbook discovery and execution
• tasks - Task operations
• tenants - Multi-tenancy operations
• kubernetes - Kubernetes operations
• machines - Deployment target operations
• certificates - Certificate operations
• accounts - Account operations
• interruptions - Manual intervention and approval operations
• featureToggles - Inspect and adjust customer feature toggles
• context - Authenticated user and project context (current user, Git branches)

Read-Only Mode

The server runs with write tools enabled by default. Pass --read-only to disable all write tools and block POST/PUT/PATCH/DELETE through the execute backstop. Most curated tools are already read-only; only a small set perform writes.

Write-enabled tools (always-write):

• create_release - Create new releases
• deploy_release - Deploy releases to environments and tenants
• run_runbook - Run a runbook against one or more environments (and optional tenants)
• update_feature_toggle - Adjust per-environment state and rollout percentages on an existing feature toggle

Conditionally-writing tool: execute is a structured REST backstop whose tier (read / write / delete) is determined by the HTTP method passed to it. See the API Catalog & Backstop section for details.

Write tools are gated by an MCP elicitation prompt: clients that support elicitation will be asked to confirm before the call proceeds. Clients without elicitation support must pass confirm: true in the tool arguments — otherwise the tool aborts with an error. Set OCTOPUS_SKIP_ELICITATION=true to bypass the gate entirely (intended for unattended automation).

The server uses a three-tier read/write/delete classification, enforced server-side based on the HTTP method (the agent cannot bypass this by lying about intent):

• read — always allowed. GET requests through execute, plus all find_* / get_* / list_* tools.
• write — POST/PUT/PATCH through execute and the always-write tools above. Blocked when --read-only is set.
• delete — DELETE through execute. Requires --allow-deletes and is blocked when --read-only is set. A small set of catastrophic-delete paths (e.g. DELETE /api/spaces/{id}, DELETE /api/users/{id}) and API-key endpoints are on a hard sensitive denylist that ignores both flags.

# 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 --re