Official Octopus Deploy MCP Server — Query, Inspect, Manage

Overview

The Official Octopus Deploy MCP Server implements the Model Context Protocol (MCP) for interacting with an Octopus Deploy instance. It provides a lightweight server that mediates between Octopus’ REST API and client tools, allowing you to query and inspect the model (projects, environments, releases, deployments, machines, variables) and to perform controlled management operations from external tooling and automation.

MCP Server is intended for developers and SREs who want a stable, focused interface to Octopus data and actions for integrations, dashboards, and automation pipelines. Instead of having every tool call the Octopus API directly, you can run an MCP Server instance that caches, normalizes, and exposes a consistent set of endpoints and protocols for querying and controlling your deployment model.

Features

• Query the Octopus model (projects, environments, processes, releases, machines, variables) via a single endpoint surface
• Inspect resource relationships and metadata for diagnostics and visualization
• Execute management operations (trigger deployment, cancel/deploy tasks, snapshot configuration) in a controlled manner
• Optional caching to reduce load against the Octopus server and speed repeated queries
• TLS support and basic authentication or API-key-backed requests
• Docker image and standalone binary for easy deployment
• Extensible architecture to add custom endpoints or integrations

Installation / Configuration

There are multiple ways to run the MCP Server: Docker, systemd (binary), or build from source. Replace placeholders (<…>) with your real values.

Run with Docker

docker run -d \
  --name octo-mcp \
  -p 8080:8080 \
  -e OCTOPUS_URL="https://octopus.example.com" \
  -e OCTOPUS_API_KEY="API-XXXXXXXXXXXXXXXX" \
  -e MCP_BIND_ADDRESS="0.0.0.0:8080" \
  -e MCP_CACHE_ENABLED="true" \
  octopusdeploy/mcp-server:latest

Run as a standalone binary (Linux)

# download and unpack the latest release from GitHub Releases
wget https://github.com/OctopusDeploy/mcp-server/releases/download/vX.Y.Z/mcp-server-linux-amd64.tar.gz
tar xzf mcp-server-linux-amd64.tar.gz
./mcp-server --octopus-url "https://octopus.example.com" --api-key "API-XXXXXXXX" --bind "0.0.0.0:8080"

Sample systemd unit

[Unit]
Description=Octopus MCP Server
After=network.target

[Service]
User=octopus
ExecStart=/opt/mcp-server/mcp-server \
  --octopus-url=https://octopus.example.com \
  --api-key=API-XXXXXXXX \
  --bind=0.0.0.0:8080 \
  --cache-enabled=true
Restart=on-failure
Environment=TZ=UTC

[Install]
WantedBy=multi-user.target

Sample YAML configuration (if supported)

octopus:
  url: https://octopus.example.com
  apiKey: API-XXXXXXXX
server:
  bind: 0.0.0.0:8080
  tls:
    certFile: /etc/ssl/certs/mcp.crt
    keyFile: /etc/ssl/private/mcp.key
cache:
  enabled: true
  ttlSeconds: 300
auth:
  jwtSecret: change-me

Configuration reference (common environment variables and flags)

Available Resources

• GitHub repository and releases: https://github.com/OctopusDeploy/mcp-server
• Built-in API documentation: /docs or /swagger (when the server is running)
• Example clients and integrations: see the repository’s examples folder for sample scripts and client libraries
• Logs and metrics: endpoints for health (/health), metrics (/metrics), and debug (/debug) (if enabled)

Use Cases

1. Query deployment status for dashboards

# Get latest deployments for a project and format with jq
curl -s "http://mcp-server:8080/api/v1/projects/<ProjectID>/deployments?limit=10" \
  -H "Authorization: Bearer <MCP_TOKEN>" | jq '.items[] | {id, environment, state, created}'

Returns a normalized list of recent deployments that your dashboard app can consume without calling Octopus directly.

2. Inspect a release process to build visual diagrams

curl -s "http://mcp-server:8080/api/v1/projects/<ProjectID>/process" \
  -H "Authorization: Bearer <MCP_TOKEN>" | jq .

Use the returned structured process model to render step trees, variable scopes, and target roles in a UI.

3. Trigger a deployment from CI/CD with validation

curl -X POST "http://mcp-server:8080/api/v1/deployments" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <MCP_TOKEN>" \
  -d '{
    "projectId": "<ProjectID>",
    "releaseVersion": "1.2.3",
    "environmentId": "<EnvID>"
  }'

MCP Server can validate the request against project constraints and optional policy checks before forwarding the action to Octopus.

4. Reduce load on Octopus during large reporting jobs

• Use MCP Server’s caching layer to batch and cache model queries for analytics jobs that need to scan many projects and environments.

Getting