# Octopus Deploy MCP Server

A Model Context Protocol (MCP) server for interacting with Octopus Deploy. This server provides tools for managing projects, releases, and deployments through the MCP protocol.

## Features

- **Project Management**: List and query Octopus Deploy projects
- **Release Management**: Get latest releases and create new releases
- **Deployment Management**: Deploy releases and check deployment status
- **Multi-Space Support**: Work with different Octopus Deploy spaces
- **Docker Support**: Containerized deployment for easy integration

## Installation

### 1. Clone the Repository

```bash
git clone https://github.com/armanzeroeight/octopus-deploy-mcp-server.git
cd octopus-deploy-mcp
```

### 2. Build Docker Image

```bash
./scripts/build.sh
```

This will create a Docker image tagged as `octopus-deploy-mcp:latest`.

## MCP Configuration

Add the following configuration to your MCP client's `mcp.json` file:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "octopus-api-key",
      "description": "Octopus Deploy API key",
      "password": true
    }
  ],
  "servers": {
    "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}"
      }
    }
  }
}
```

### Configuration Notes

- Replace `https://your-octopus-server.com` with your actual Octopus Deploy server URL (without `/api` suffix)
- The API key will be prompted securely when the MCP client starts
- The Docker image must be built locally using the build script

## Available Tools

### Project Tools
- `list_projects`: List all projects in a space
- `get_project_details`: Get detailed information about a specific project

### Release Tools
- `get_latest_release`: Get the latest release for a project
- `create_release`: Create a new release for a project

### Deployment Tools
- `deploy_release`: Deploy a release to an environment
- `check_deployment_status`: Check the status of deployments

## Development

### Local Setup (without Docker)

```bash
# Install UV if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

# Set up environment variables
cp .env.sh.example .env.sh
# Edit .env.sh with your Octopus Deploy credentials

# Run the server directly
source .env.sh

# Install the package in editable mode
uv pip install -e .
uv run octopus-deploy-mcp

# Or use fastmcp-cli tool for development
fastmcp dev dev.py
```

### Testing Docker Build

```bash
# Test the Docker image locally
./scripts/test-docker.sh
```

## Requirements

- Docker
- Your Octopus Deploy server URL
- Valid Octopus Deploy API key with appropriate permissions

## Troubleshooting

### Common Issues

1. **"Space 'Default' not found"**
   - Verify your Octopus server URL is correct
   - Check that your API key has access to the specified space
   - Ensure the space name exists (case-sensitive)

2. **"Authentication failed"**
   - Verify your API key is correct and hasn't expired
   - Check that the API key has the necessary permissions

3. **Docker build fails**
   - Ensure Docker is running
   - Check that you have sufficient disk space
   - Verify internet connectivity for downloading dependencies

### Debug Mode

The server automatically enables debug logging. Check the MCP client logs for detailed error information.

## Support

For issues and questions, please create an issue on GitHub.