# mcp-server [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/OctopusDeploy/mcp-server  
**GitHub Stars:** 102  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-server-181

## Description
Octopus Deploy Official MCP Server

## Tools
Capabilities this server exposes over MCP:

- **list_spaces** — List all spaces in the Octopus Deploy instance. Spaces is the main organizational unit in Octopus Deploy, Spaces keep the different projects, infrastructure and tenants completely separate. Spaces typically represent team or project boundary, but not customer boundary (use tenants for those). Always use this tool first to check that the requested space exists.
- **list_projects** — This tool lists all projects in a given space. Projects let you manage software applications and services, each with their own deployment process, lifecycles, and variables. Projects are where you define what you are deploying and how it should be deployed. The space name is required, if you can't find the space name, ask the user directly for the name of the space. Optionally filter by partial name match using partialName parameter.
- **list_environments** — List environments in a space

  This tool lists all environments in a given space. The space name is required. Use this tool as early as possible to understand which environments are configured. Optionally filter by partial name match using partialName parameter.
- **list_deployments** — List deployments in a space

  This tool lists deployments in a given space. The space name is required. When requesting latest deployment consider which deployment state the user is interested in (successful or all). Optional filters include: projects (array of project IDs), environments (array of environment IDs), tenants (array of tenant IDs), channels (array of channel IDs), taskState (one of: Canceled, Cancelling, Executing, Failed, Queued, Success, TimedOut), and take (number of results to return).
- **get_tenant_variables** — Get tenant variables by type

  This tool retrieves different types of tenant variables. Use variableType parameter to specify which type:
  - "all": Get all tenant variables
  - "common": Get common variables only
  - "project": Get project-specific variables only
- **get_missing_tenant_variables** — Get missing tenant variables

  This tool retrieves tenant variables that are missing values. Optionally filter by tenant, project, or environment.
- **get_kubernetes_live_status** — Get Kubernetes live status for a project and environment

  This tool retrieves the live status of Kubernetes resources for a specific project and environment. Optionally include a tenant ID for multi-tenant deployments.
- **get_deployment_process** — Get deployment process by ID

This tool retrieves a deployment process by its ID. Each project has a deployment process attached, and releases/deployments can also have frozen processes attached.
- **get_branches** — Get Git branches for a version-controlled project

This tool retrieves Git branches for a specific project in a space. The space name and project ID are required. Optionally provide searchByName, skip, and take parameters for filtering and pagination.
- **get_current_user** — Get information about the current authenticated user

This tool retrieves information about the currently authenticated user from the Octopus Deploy API.
- **get_variables** — This tool gets all project and library variable set variables for a given project.
        Projects can contain variables (specific to a project), library variable sets (shared collections of variables associated with many projects),
        and tenant variables (variables related to a tenants connected to the project)
        If you want to retrieve tenant variables for a tenant connected to the project, use the get_tenant_variables tool.
        
- **get_task_from_url** — Get task details from an Octopus Deploy task URL. Returns full task details including execution logs and state.

This tool is a URL-to-ID resolver that returns the **same body** as the `octopus://spaces/{spaceName}/tasks/{taskId}/details` resource — no need to dereference the URI afterward. If you only need lightweight metadata for polling (state, timing, completion flags) use the smaller `octopus://spaces/{spaceName}/tasks/{taskId}` resource instead.

Accepts task URLs like:
https://your-octopus.com/app#/Spaces-1/tasks/ServerTasks-456

Key features:
- Returns full task details including execution logs
- Handles space ID to space name resolution automatically
- Validates task ID format

For deployment URLs:
If you have a deployment URL, use this workflow:
1. Call get_deployment_from_url with the deployment URL
2. Use the returned taskResourceUri (structured tree) or call grep_task_log with the returned taskId to search the raw log

Tasks represent background operations in Octopus Deploy, such as deployments, health checks, and system maintenance. Each task has a unique ID and can be monitored for status and progress.
- **get_deployment_from_url** — Get deployment details from an Octopus Deploy deployment URL. Returns comprehensive deployment information including the task ID needed to view execution logs.

Accepts deployment URLs like:
https://your-octopus.com/app#/Spaces-1/projects/my-app/deployments/releases/1.0.0/deployments/Deployments-123

Returns:
- Full deployment details (environment, release, project, created time)
- taskIdForLogs: the ServerTasks- ID for this deployment
- taskResourceUri: octopus:// URI for the structured activity tree (resources/read or read_resource)
- grepTaskLogHint: pre-filled arguments for the grep_task_log tool — call it with a pattern to search the raw log without fetching the whole thing
- Public URL for web portal access

Recommended workflow for investigating deployment issues:
1. Call get_deployment_from_url with the deployment URL
2. Review deployment context (environment, release version, etc.)
3a. Fetch the taskResourceUri for the structured activity tree (step timings, embedded log entries by category), OR
3b. Call grep_task_log with the taskId to search the raw log for a specific error / pattern

Handles space ID to space name resolution automatically.
- **find_releases** — Find releases in an Octopus Deploy space.

  Three modes, picked by which arguments are supplied:
  - releaseId  → fetch the summary for that release.
  - projectId  → list releases for that project (optionally filtered by searchByVersion).
  - neither    → list releases across the space.

  Each summary includes a resourceUri for fetching the full release body
  (release notes, packages, build information, custom fields).
- **find_runbooks** — Find runbooks in an Octopus Deploy project.

Two project kinds are supported:
- DB-backed projects: address runbooks by 'runbookId' (e.g. 'Runbooks-123'). The summary includes 'publishedRunbookSnapshotId', which run_runbook uses by default.
- Config-as-Code (CaC) projects: pass 'gitRef' (branch name like 'main', tag, or commit SHA). Address a single runbook by 'runbookSlug'. The summary includes 'gitRef' instead of 'publishedRunbookSnapshotId'; run_runbook needs the same gitRef.

Modes:
- runbookId             → fetch a single DB runbook.
- runbookSlug + gitRef  → fetch a single CaC runbook.
- gitRef alone          → list CaC runbooks at that ref.
- neither               → list DB runbooks in the project (optionally filtered by partialName).

Each summary includes multiTenancyMode and environmentScope so callers can determine which environments and tenants are valid targets before invoking run_runbook.
- **find_tenants** — Find tenants in a space - can retrieve a single tenant by ID or list all tenants

  This unified tool can either:
  - Get details for a specific tenant when tenantId is provided, including the projects and environments the tenant is associated with
  - List all tenants in a space when tenantId is omitted

  Tenants represent customers or clients in Octopus Deploy, allowing you to manage deployments and configurations specific to each tenant. Tenants can be grouped into tenant tags for easier management and deployment targeting. Tenants can also represent geographical locations, organizational units, or any other logical grouping.

  Optionally provide filtering and pagination parameters when listing.
- **find_deployment_targets** — Find deployment targets (machines) in a space - can retrieve a single target by ID or list all targets

This unified tool can either:
- Get detailed information about a specific deployment target when targetId is provided
- List all deployment targets in a space when targetId is omitted

You can optionally filter by various parameters like name, roles, health status, etc. when listing.
- **find_certificates** — Find certificates in a space - can retrieve a single certificate by ID or list all certificates

This unified tool can either:
- Get detailed information about a specific certificate when certificateId is provided
- List all certificates in a space when certificateId is omitted

You can optionally filter by various parameters like name, archived status, tenant, etc. when listing.
- **find_accounts** — Find accounts in a space - can retrieve a single account by ID or list all accounts

This unified tool can either:
- Get detailed information about a specific account when accountId is provided
- List all accounts in a space when accountId is omitted

You can optionally filter by various parameters like name, account type, etc. when listing.
- **find_interruptions** — Find interruptions (manual interventions, guided failures, deployment approvals) in an Octopus Deploy space.

Interruptions are the Octopus surface equivalent to pending approvals: a deployment or runbook run pauses and waits for a human to take action. Use this tool to enumerate them or to look up a single one.

Modes (picked by which arguments you supply):
- interruptionId  → fetch the slim summary for that interruption.
- assignedToMe    → list interruptions the authenticated user can act on; resolves /users/me (cached per session).
- regarding       → list interruptions related to a specific entity (ServerTasks-…, Deployments-…). Native server-side filter.
- (none)          → list all interruptions, optionally filtered by pendingOnly (default: true) and skip/take.

Each summary includes:
- resourceUri      → octopus://spaces/{spaceName}/interruptions/{id} for the FULL body (form definition with Markdown instructions, button options, control types, and any already-submitted values). Dereference this when the user asks for details about a specific interruption.
- taskResourceUri  → octopus://spaces/{spaceName}/tasks/{taskId} for the surrounding deployment/runbook task.
- publicUrl        → Octopus portal deep link to take action.
- formElementNames → just the field names (e.g. Instructions, Notes, Result). Field values are NOT in the slim summary; fetch resourceUri for those.
- **find_events** — Search the Octopus Deploy audit log (also called the Events log) — every meaningful action recorded against a space: deployments, release creations, modifications, user logins, machine registrations, variable edits, tenant changes, and so on.

**Modes** (the `mode` arg):
- `search` (default) — query the audit log. Requires `spaceName`. Supports rich filtering by user, project, environment, tenant, document type, date range, category, group, and agent.
- `listCategories` — enumerate every event category (e.g. `DeploymentSucceeded`).
- `listGroups` — enumerate event groups (e.g. `Created`, `Modified`, `Deleted`, `Deployment`). Each group lists the categories inside it.
- `listAgents` — enumerate user-agent strings recorded by the audit subsystem.
- `listDocumentTypes` — enumerate entity-prefix metadata (`Projects-`, `Releases-`, ...).

**Search modes** (within `mode='search'`, picked by argument shape):
- `eventId` → fetch that single event. Mutually exclusive with list and pagination filters; `excludeDifference` is still honoured.
- otherwise → list events matching the filters, paginated.

**Performance tip:** the per-event `ChangeDetails` field (the before/after diff for Modified events) is by far the heaviest payload field. Pass `excludeDifference: true` whenever scanning many events; fetch a single event without the flag when you need the diff.

**Filter semantics:**
- `regarding` — AND semantics: event must reference EVERY listed document ID.
- `regardingAny` — OR semantics: event must reference ANY listed document ID.
- All other multi-value filters (users, projects, environments, tenants, eventCategories, eventGroups, ...) are OR semantics within the field.
- `from` (inclusive) and `to` (exclusive) accept ISO 8601 datetimes.

**Permissions:** requires `EventView` on the calling user's space scope. The server filters results further based on per-document permissions.
- **find_feature_toggles** — List customer feature toggles in an Octopus Deploy project.

Each summary includes per-environment state (isEnabled, rolloutPercentage, clientRolloutPercentage) so "where is X turned on" is answerable from the list response. Heavy fields (description, tenant lists, segments, minimum versions) live in the resource body.

Dereference the returned resourceUri (octopus://spaces/{spaceName}/projects/{projectId}/featuretoggles/{slug}) for the full toggle body.

Use update_feature_toggle to flip an environment on/off or change rollout percentages on an existing toggle. This MCP server does not expose toggle creation, deletion, renaming, or rollout-group management — direct customers to the Octopus UI for those.
- **update_feature_toggle** — Adjust an existing customer feature toggle in an Octopus Deploy project.

Narrow surface — flip an environment on/off, change rollout percentages, or update the toggle-level description / default state. Internally fetches the current toggle, applies your patches in memory, and PUTs the merged body, so unmentioned environments and unmentioned fields are preserved.

Deliberately not exposed: name/slug rename, tag changes, rollout group attach/detach, tenant targeting, segments, minimum version, adding or removing environment configurations entirely. For those, use the Octopus UI.

Patches that reference an environment not already configured on the toggle are rejected with reason: environment_not_configured. The tool does not add new environment configurations.
- **create_release** — Create a new release for an Octopus Deploy project

This tool creates a new release for a project. The space name and project name are required. All other parameters are optional and will use Octopus defaults if not specified.
- **deploy_release** — Deploy a release to one or more environments in Octopus Deploy

This tool supports both tenanted and untenanted deployments:
- **Untenanted**: Don't provide tenants or tenantTags. Can deploy to multiple environments at once.
- **Tenanted**: Provide tenants or tenantTags. Can only deploy to ONE environment, but can target multiple tenants.

The tool automatically determines which deployment type to use based on the parameters provided.
- **run_runbook** — Run a runbook against one or more environments in Octopus Deploy.

Runbooks execute operational processes (DB backups, smoke tests, environment refresh, etc.) against the specified environments. For tenanted runs, supply tenants and/or tenantTags.

Two project kinds:
- DB-backed projects: by default the runbook's published snapshot is used; pass runbookSnapshotId to pick a specific snapshot.
- Config-as-Code projects: pass gitRef (branch name like 'main', tag, or commit SHA). Snapshots don't apply — the gitRef is the version pin. Use find_runbooks with the same gitRef to discover runbook names.
- **grep_task_log** — Search a server task's activity log with grep-style semantics. Returns only matching lines (with optional symmetric context windows). This is the canonical way to inspect task logs — there is no full-log resource URI, because exposing one would tempt callers to inhale multi-megabyte bodies when grep is almost always the better primitive.

Use this when you know what to look for (a specific error string, a step name, a pattern). For structured access to the activity tree (step hierarchy, categories, timing) use the octopus://spaces/{spaceName}/tasks/{taskId}/details resource instead.

Parameter conventions mirror GNU grep so the schema is self-explanatory:
- pattern (regex by default; set fixedString:true for literal text)
- caseInsensitive   (-i)
- invertMatch       (-v)
- fixedString       (-F)
- beforeContext     (-B)
- afterContext      (-A)
- maxCount          (-m)

Response includes totalMatches (true count across the whole log), totalLines, the matched lines with 1-indexed lineNumber, optional before/after context arrays, and a taskDetailsResourceUri for the structured fall-through.
- **grep_llms_txt** — Search the Octopus API catalog at octopus://api/llms.txt with grep-style semantics. The catalog is large (~300+ KB) — call this rather than reading the resource body directly.

llms.txt is structured as:
- Authentication and Space Selection sections (top of file)
- Endpoints section: one '### {Category}' heading per resource family (Accounts, ActionTemplates, Channels, Releases, …) and one bullet per endpoint of the form
    `- \`METHOD /path\` - description | Prefixes (pick one): /{spaceId}, /spaces/{spaceIdentifier} | ?queryParams → ReturnType`
- Steps section: deployment step types (Octopus.* ActionType) and their configurable property keys.

Useful patterns:
- 'POST /releases'   — find write endpoints under a resource family
- 'DELETE '          — enumerate delete endpoints
- '### Channels'     — jump to a section heading
- 'Body: Create.*Command' — find endpoints that take a Create command body

Parameter conventions mirror GNU grep:
- pattern (regex by default; set fixedString:true for literal text)
- caseInsensitive   (-i)
- invertMatch       (-v)
- fixedString       (-F)
- beforeContext     (-B)
- afterContext      (-A)
- maxCount          (-m)

Response: totalMatches (true count across the whole file), totalLines, the matched lines with 1-indexed lineNumber, optional before/after context arrays, and catalogResourceUri for the structured fall-through.
- **execute** — Reach Octopus REST endpoints not covered by the curated tools. Use this only after grep_llms_txt has shown you the right method and path.

**Method gating is hard-coded server-side, three tiers:**

  - GET    → read tier: always allowed (subject to toolset allowlist + sensitive denylist).
  - POST/PUT/PATCH → write tier: blocked when --read-only is set; requires user confirmation via elicitation otherwise.
  - DELETE → delete tier: requires --allow-deletes (and is blocked when --read-only is set) AND a stronger user confirmation.

The HTTP method enum is the gate. The tool will not honour any 'isRead' flag the agent invents — the runtime classifies based on the actual method.

**Other gates** (in order):
  0. Path shape: must be '/api' or start with '/api/'. Absolute URLs, '~/api/...', '/octopus/portal/...', query strings, fragments, '..' segments, and percent-encoded slashes are all rejected up front.
  1. Sensitive denylist: API key endpoints and catastrophic deletes (DELETE /api/users/{id}, DELETE /api/spaces/{id}) are always blocked.
  2. Path allowlist — only applied when --toolsets has narrowed the active set. With every toolset enabled (the default, or explicit --toolsets all) any path under /api is reachable subject to the other gates; when toolsets are narrowed, paths only resolve if their owning toolset is enabled so disabling a toolset (e.g. 'certificates') makes its endpoints unreachable even on GET.
  3. Elicitation on every non-GET, with a stronger message for DELETE.

Discover endpoints with grep_llms_txt. Use octopus://api/capabilities to see which toolsets are enabled and whether write/delete modes are on.
- **read_resource** — Universal fetch for any 'octopus://' URI returned by any other tool. Use this whenever you see fields like 'resourceUri' or 'taskResourceUri' in a response and need the full body.

How to use:
- Pass the URI string verbatim. Examples: 'octopus://spaces/Default/releases/Releases-42', 'octopus://spaces/Default/tasks/ServerTasks-7', 'octopus://spaces/Default/tasks/ServerTasks-7/details'.
- The response 'mimeType' tells you how to interpret 'text': 'application/json' → parse as JSON.

This tool is the backstop for clients that do not natively implement the MCP 'resources/read' primitive. Clients that DO support resources/read (Claude Code, MCP Inspector) can call it directly and skip this tool. Either path returns byte-identical bodies.

Tools that return resource URIs include: find_releases, get_deployment_from_url, get_task_from_url, and others. When in doubt, call read_resource on any 'octopus://' string you encounter.

Note: there is intentionally no octopus://...tasks/{id}/log resource. Call the grep_task_log tool to search task logs without inhaling the full body.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp-server": {
    "command": "npx",
    "args": ["-y","@octopusdeploy/mcp-server"],
    "env": {
      "OCTOPUS_SERVER_URL": "",
      "OCTOPUS_API_KEY": "",
      "OCTOPUS_ACCESS_TOKEN": ""
    }
  }
}
```

**Requires environment variables:** `OCTOPUS_SERVER_URL`, `OCTOPUS_API_KEY`, `OCTOPUS_ACCESS_TOKEN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What mcp-server does

mcp-server exposes Octopus Deploy operations to MCP-compatible AI clients. It is intended for querying and diagnosing an Octopus instance, while also supporting selected operational actions when write access is enabled. Available areas include projects, deployments, releases, runbooks, tasks, tenants, Kubernetes resources, deployment targets, certificates, accounts, interruptions, feature toggles, and authenticated-user or project context.

The server supports Octopus Server APIs, with most tools compatible with APIs available from Octopus Server 2021.1 onward. Individual tools may require newer server versions. Use `--list-tools-by-version` to inspect tool compatibility by version.

## How it works

The server communicates with an AI client through MCP over stdio. It can be started with Docker or launched from npm using `npx -y @octopusdeploy/mcp-server`. The Octopus instance must be reachable over HTTPS.

Authentication uses either an Octopus API key or a Bearer access token. API keys are intended for interactive and long-running use; short-lived access tokens are intended for automated workflows such as CI/CD or machine-to-machine processes. If both credentials are set, the access token takes precedence.

Write operations are enabled by default. The `--read-only` option removes write tools and blocks POST, PUT, and PATCH/DELETE requests through the structured `execute` backstop. Write-capable operations include creating releases, deploying releases, running runbooks, updating feature toggles, and HTTP actions issued through `execute`.

## Setup and configuration

Node.js 20 or newer is required for the npm installation. Configure the server in the MCP client with a stdio command and provide `OCTOPUS_SERVER_URL` plus either `OCTOPUS_API_KEY` or `OCTOPUS_ACCESS_TOKEN` in the environment. The server URL can instead be passed with `--server-url`; credentials must remain environment variables so they are not exposed in the process list.

Docker users can run the `octopusdeploy/mcp-server` image with `-i`, passing the same environment variables. On Apple Macs, the Docker configuration may need `--platform linux/amd64`.

Use `--toolsets` to limit the exposed capabilities, such as `projects,deployments`, or use `all` to enable every toolset. The core toolset is always enabled. Configure `--read-only` for production sessions where the assistant should not alter Octopus state.

## Tools and capabilities

- Inspect and query projects, deployments, releases, tasks, tenants, and runbooks.
- Discover and execute runbooks against environments and optional tenants.
- Create and deploy releases when writes are enabled.
- Inspect deployment targets, Kubernetes resources, accounts, certificates, interruptions, and feature toggles.
- View authenticated-user and project context, including Git branches.
- Use `execute` as a structured REST backstop, subject to read-only restrictions.

## Limitations and notes

This repository is deprecated. Octopus Server 2026.3 and later provide a Remote MCP Server, which is the replacement direction for newer installations. Access tokens should be short-lived and used for automated scenarios rather than as long-lived credentials. The server's supported tool and API versions can vary by operation, so check tool-version mappings before relying on newer capabilities.

_Full upstream README: https://allmcps.com/mcp/mcp-server-181/readme_