Octopus Deploy Mcp Server
About
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.
Details
- Author
- armanzeroeight
- Downloads
- 144
- Categories
- Developer Tools, Infrastructure, Other
Jump to
- Project management: list and query projects
- Release management: get latest releases and create releases
- Deployment management: deploy releases and check status
- Multi-space support for different Octopus spaces
- Docker support for containerized deployment
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Octopus Deploy Mcp ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Clone the repository, build the Docker image using ./scripts/build.sh, then configure your MCP client's mcp.json file with the Octopus server URL and API key. The server runs as a Docker container communicating over stdio.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"octopus deploy mcp server": {
"octopus-deploy-mcp-server": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"OCTOPUS_URL",
"-e",
"OCTOPUS_API_KEY",
"octopus-deploy-mcp:latest",
"octopus-deploy-mcp"
],
"env": {
"OCTOPUS_URL": "https://your-octopus-server.com",
"OCTOPUS_API_KEY": "${input:octopus-api-key}"
}
}
}
}
}McpServers
{
"octopus-deploy-mcp-server": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"OCTOPUS_URL",
"-e",
"OCTOPUS_API_KEY",
"octopus-deploy-mcp:latest",
"octopus-deploy-mcp"
],
"env": {
"OCTOPUS_URL": "https://your-octopus-server.com",
"OCTOPUS_API_KEY": "${input:octopus-api-key}"
}
}
}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.
What can you do with Octopus Deploy Official MCP?
- Investigate a deployment from its URL— paste an Octopus deployment URL and let the assistant fetch details and the associated task ID viaget_deployment_from_url.
- Search task logs for errors without downloading the full log— usegrep_task_logwith a pattern like “error|fail” to find matching lines and context in a task’s activity log.
- Discover available REST endpoints— callgrep_llms_txtto search the Octopus API catalog for endpoints, request bodies, or delete operations before using theexecutebackstop.
- Find and inspect releases— usefind_releasesto locate a release by project or ID, then fetch its full body (release notes, packages) via theoctopus://spaces/{spaceName}/releases/{releaseId}resource.
- Check Kubernetes resource status for a project and environment— callget_kubernetes_live_statusto retrieve live status of Kubernetes resources (requires Octopus 2025.3+).
- Manage feature toggle states across environments— list toggles withfind_feature_togglesand adjust per-environment enabled state or rollout percentages withupdate_feature_toggle.
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 ourdocumentation.
Most tools exposed by the MCP Server use stable APIs that have been available from at least version2021.1of 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-versionto check how specific tools relate to versions of Octopus.
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-urlflag.
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.
- 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 (seeAuthenticationbelow)
Full example configuration (for Claude Desktop, Claude Code, and 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" } } } }
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'snpxcommand. 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 theOCTOPUS_SERVER_URLenvironment variable or the--server-urlflag.
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
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 intendedonly for automated scenarioswhere 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.
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.
Use the--toolsetsparameter 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
- 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)
The server runs with write tools enabled by default. Pass--read-onlyto disable all write tools and block POST/PUT/PATCH/DELETE through theexecutebackstop. Most curated tools are already read-only; only a small set perform writes.
- 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:executeis a structured REST backstop whose tier (read / write / delete) is determined by the HTTP method passed to it. See theAPI Catalog & Backstopsection 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 passconfirm: truein the tool arguments — otherwise the tool aborts with an error. SetOCTOPUS_SKIP_ELICITATION=trueto 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 throughexecute, plus allfind_/get_/list_tools.
- write— POST/PUT/PATCH throughexecuteand the always-write tools above. Blocked when--read-onlyis set.
- delete— DELETE throughexecute. Requires--allow-deletesand is blocked when--read-onlyis 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 --read-only
Security Note:Use an API key with appropriate, least-privilege permissions — write operations can create releases and trigger deployments in your Octopus instance. For production, consider passing--read-onlyunless you have a specific, controlled use case for writes.--allow-deletesis off by default; only enable it when the agent must issue DELETE requests throughexecute. If you pass--allow-deletestogether with--read-only, the server prints a startup warning to stderr — DELETE requests remain blocked by the read-only gate.
All examples below assumeOCTOPUS_API_KEYis set in the environment. The--server-urlflag is shown for clarity but can also be provided viaOCTOPUS_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- Enable read-only mode: disable all curated write tools and block POST/PUT/PATCH/DELETE throughexecute. Writes are enabled by default; this flag turns them off. SeeRead-Only Mode.
- --allow-deletes- Permit DELETE requests through theexecutetool. Ignored (with a startup warning) when--read-onlyis set. Defaultfalse.
- --log-level <level>- Minimum log level (info, error)
- --log-file <path>- Log file path or filename. If not specified, logs are written to console only
- -q, --quiet- Disable file logging, only log errors to console
- --list-tools-by-version- List all registered tools by their supported Octopus Server version and exit
Quick start: Paste Octopus URLs directly to investigate issues without manual ID extraction.
- get_deployment_from_url: Get deployment details from deployment URL (returns taskId for follow-up)
- get_task_from_url: Get task details and logs from task 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 })
get_task_from_url with task URL → Returns task details and logs immediately
These tools eliminate manual ID extraction by:
- Parsing URLs automatically
- Resolving space IDs to space names
- Validating ID formats
- Providing clear error messages
- Deployment:https://your-octopus.com/app#/Spaces-1/projects/my-app/deployments/Deployments-123
- Task:https://your-octopus.com/app#/Spaces-1/tasks/ServerTasks-456
SeeWorking with URLsfor detailed workflows, examples, and best practices.
- list_spaces: List all spaces in the Octopus Deploy instance
- list_environments: List all environments in a given space
These tools and resources let the agent reach Octopus REST endpoints that don't have a dedicated curated tool, with hard server-side gating between read, write, and delete operations.
- grep_llms_txt: Search the Octopus API catalog (octopus://api/llms.txt) with grep-style semantics (minimum supported Octopus version:2026.2.3916). The catalog body is large (typically 300+ KB) — call this rather than reading the resource body directly. Parameters mirror GNU grep (pattern,caseInsensitive,invertMatch,fixedString,beforeContext,afterContext,maxCount). Useful for discovering endpoints (POST /releases), enumerating delete endpoints (DELETE), or finding the body type for a write operation (Body: Create.Command).
- execute: Structured REST backstop. Reaches any Octopus REST endpoint under/api. The HTTP method is the authoritative read/write/delete classifier — never anisWriteflag the LLM can set. Method gating is hard-coded server-side:
- GETis always allowed (subject to the path shape check + sensitive denylist).
- POST/PUT/PATCHare blocked when--read-onlyis set; otherwise they require user confirmation via elicitation.
- DELETErequires--allow-deletes(and is blocked when--read-onlyis set) plus a stronger "IRREVERSIBLE" elicitation message.
- The sensitive denylist (API-key endpoints,DELETE /api/spaces/{id},DELETE /api/users/{id}) is enforced even with both flags on.
- The path is required to be/apior start with/api/— absolute URLs, SDK-relative~/api/...paths, and host-relative paths outside/api(e.g./octopus/portal/...) are rejected up front, soexecutestays bounded to the Octopus REST API surface.
- Per-toolset path allowlist applies only when--toolsetshas been narrowed.With every toolset enabled (the default, or explicit--toolsets all) the allowlist is bypassed and any path under/apiis reachable subject to the gates above. When--toolsetsis narrowed the allowlist becomes the kill-switch: paths only resolve if their owning toolset is enabled, so disabling a toolset (e.g.certificates) makes its paths unreachable throughexecuteeven onGET.
Catalog data is also exposed as MCP Resources:
- octopus://api/llms.txt— markdown catalog of every Octopus REST endpoint (HTTP method, path, query params, request/response types). Requires Octopus Server2026.2.3916or later. 5-minute in-memory cache keyed on the configured server URL.Prefergrep_llms_txtto reading the body directly.
- octopus://api/capabilities— JSON describing the running session: server version, enabled toolsets, available tools (with theirminimumOctopusVersion), and whether--read-only/--allow-deletesis on. Useful for the agent to discover what's reachable in this session.
- list_projects: List all projects in a given space
- deploy_release: Deploy a release to environments (supports both tenanted and untenanted deployments)
- list_deployments: List deployments in a space with optional filtering
- create_release: Create a new release for a project
- find_releases: Find releases in a space (can get a specific release by ID, or list/filter releases by project)
Release detail is also available as an MCP Resource atoctopus://spaces/{spaceName}/releases/{releaseId}— fetch viaresources/read(or theread_resourcebackstop tool) to get the full release body, including release notes and selected packages.
- find_runbooks: Find runbooks in a project (can get a specific runbook by ID, or list/filter runbooks by partial name). Each summary includes the published snapshot ID, multi-tenancy mode, and environment scope so callers can pick valid targets before running.
- run_runbook: Run a runbook against one or more environments. Supports tenanted runs (by tenant name or tenant tag), prompted variables, guided failure mode, scheduled run windows, and step or machine inclusion/exclusion. Defaults to the runbook's published snapshot ifrunbookSnapshotIdis omitted.
The full runbook body (including runtime policy fields) is available as an MCP Resource atoctopus://spaces/{spaceName}/runbooks/{runbookId}.
Task data is primarily exposed as MCP Resources. Useresources/read(or theread_resourcebackstop tool) with one of:
- octopus://spaces/{spaceName}/tasks/{taskId}— lightweight metadata (state, timing, completion flags)
- octopus://spaces/{spaceName}/tasks/{taskId}/details— full ServerTaskDetails (Progress, ActivityLogs tree, etc.)
For log search, use thegrep_task_logtool rather than a/logresource:
- grep_task_log: Search a task's activity log without fetching the full body. Parameters mirror GNU grep (pattern,caseInsensitive,invertMatch,fixedString,beforeContext,afterContext,maxCount). Returns matching lines with 1-indexedlineNumber, optional before/after context arrays, and atotalMatchescount across the whole log.
There is intentionally no/logresource: activity logs can be multi-megabyte, and an addressable resource would tempt callers to fetch the entire body when grep is almost always the right primitive.
- find_tenants: Find tenants in a space (can get a specific tenant by ID or list/search tenants with filters)
- get_tenant_variables: Get tenant variables by type (all, common, or project)
- get_missing_tenant_variables: Get tenant variables that are missing values
- get_kubernetes_live_status: Get live status of Kubernetes resources for a project and environment (minimum supported version:2025.3)
- find_deployment_targets: Find deployment targets in a space (can get a specific target by ID or list/search targets with filters)
- find_certificates: Find certificates in a space (can get a specific certificate by ID or list/search certificates with filters)
- find_accounts: Find accounts in a space (can get a specific account by ID or list/search accounts with filters)
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
