# Morpheus MCP Server

An MCP (Model Context Protocol) server that connects Claude, Open WebUI, or any AI assistant to a live HPE Morpheus appliance. Speak in plain English — the AI translates your intent into Morpheus API calls and reports back what was done.

---

## What it does

- **Clouds** — add, list, sync, and remove cloud integrations (AWS, Azure, VMware, Nutanix, KVM, OpenStack, etc.)
- **Provisioning** — provision VMs on any cloud with full discovery of networks, plans, datastores, resource pools, and security groups
- **Instances** — start, stop, restart, delete, and inspect instances
- **Appliance Health** — CPU, memory, database, Elasticsearch, RabbitMQ status with intelligent issue detection
- **Automation** — create tasks, run scripts on instances, execute workflows
- **Service Catalog** — order catalog items, manage blueprints
- **Tenants, Roles, Users** — full RBAC management
- **License** — view license limits and current usage
- **Release Validation** — paste release notes and get an automated API test report

---

## Requirements

- Docker and Docker Compose (or Python 3.10+)
- A running HPE Morpheus appliance (version 7.x or 8.x)
- A Morpheus API token with admin or appropriate permissions
- Claude Desktop, Open WebUI, or any MCP-compatible client

---

## Setup

### Step 1 — Create your config file

```bash
cp .env.example .env
```

Open `.env` and fill in your values:

```env
MORPHEUS_URL=https://your-morpheus-instance.com
MORPHEUS_API_TOKEN=your-token-here
MORPHEUS_VERSION=8.1.0

# Transport — see "Connecting your AI client" below
MCP_TRANSPORT=sse

MCP_PORT=8000
LOG_LEVEL=INFO
MORPHEUS_VERIFY_SSL=false
```

**How to get your API token:**
Morpheus UI → top-right user icon → API Access → Generate Token

### Step 2 — Start the server

```bash
docker compose up --build -d
```

Check it started:
```bash
docker compose logs -f
```

---

## Connecting your AI client

`docker compose up --build -d` starts **two containers automatically**:
- `morpheus-mcp` on port `8000` — the MCP server
- `morpheus-mcpo` on port `8001` — OpenAPI bridge for Open WebUI

No manual mcpo setup needed.

---

### Open WebUI (any version)

1. Open **Settings → External Tools**
2. Click **+** → Add Connection
3. **URL**: `http://host.docker.internal:8001`
4. **Auth**: `None` ← must be None, not Bearer
5. **OpenAPI Spec**: leave as `openapi.json`
6. Click **Save**

Verify it's working:
```bash
curl http://localhost:8001/openapi.json | python3 -m json.tool | head -5
```

**Enable tools in chat:** click 🔧 in the chat bar. For Qwen/Llama, set **Function Calling** to `Native` in the model's Advanced Params.

> `host.docker.internal` is required — `localhost` resolves to the container, not your host.
> On Linux, if `host.docker.internal` doesn't resolve, use your host's LAN IP: `http://192.168.x.x:8001`

---

### Claude Desktop

Open the config file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Add:
```json
{
  "mcpServers": {
    "morpheus": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8000/sse"]
    }
  }
}
```

Restart Claude Desktop. Tools appear automatically.

---

## Example commands

```
"Check the Morpheus connection"
"Is the Morpheus appliance healthy?"
"Show me any health alarms"
"Get the last 50 error logs from the appliance"

"List all configured clouds"
"Show me provisioning options for the AWS cloud"
"What VMs are already running on VMware?"

"Provision an Ubuntu 24.04 VM on AWS — ask me for the details"
"Build a VM on VMware using the same settings as existing VMs"
"Stop instance 42"

"List all users"
"Show users with @company.com email"
"Show the current license and how much is used"
"Validate this release: [paste Morpheus release notes here]"
```

---

## Running without Docker

```bash
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python server.py
```

---

## SSL

Self-signed certs: `MORPHEUS_VERIFY_SSL=false` (default).
Valid certs: `MORPHEUS_VERIFY_SSL=true`.

---

## Proxmox

Proxmox requires the community plugin installed first:

1. Download JAR from [HPE Morpheus Proxmox VE Plugin](https://github.com/HewlettPackard/morpheus-proxmox-ve-plugin)
2. Install: Administration → Integrations → Plugins → Upload File
3. Run `list_zone_types` — the Proxmox code appears
4. Use that code with `add_cloud`

---

## Available Tools (80 total)

### Connection & Health
| Tool | Description |
|------|-------------|
| `check_connection` | Verify connectivity and current user |
| `get_appliance_health` | CPU, memory, DB, Elasticsearch, RabbitMQ with issue detection |
| `get_health_logs` | Appliance logs with error pattern detection |
| `get_health_alarms` | Open alarms from cloud and service integrations |
| `acknowledge_health_alarm` | Acknowledge a specific alarm |
| `acknowledge_all_health_alarms` | Clear all open alarms |

### Clouds & Infrastructure
| Tool | Description |
|------|-------------|
| `list_clouds` | List all configured clouds |
| `get_cloud_details` | Cloud type, region, status |
| `list_zone_types` | Available cloud type codes |
| `get_cloud` | Cloud details by ID |
| `add_vmware_cloud` | Add a VMware vCenter cloud |
| `add_cloud` | Add any cloud by zone type code |
| `sync_cloud` | Trigger manual cloud sync |
| `delete_cloud` | Remove a cloud integration |
| `list_groups` | List Morpheus groups/sites |
| `create_group` | Create a group |

### Discovery (use before provisioning)
| Tool | Description |
|------|-------------|
| `suggest_provision_options` | Smart discovery from running VMs — ranked options |
| `get_provision_options` | Full options for a cloud |
| `list_instance_types` | List OS/template types |
| `list_layouts` | Layouts for an instance type on a cloud |
| `list_service_plans` | VM sizes/flavors for a cloud |
| `list_networks` | Networks for a cloud |
| `list_security_groups` | Security groups for a cloud |
| `list_resource_pools` | Resource pools for a cloud |
| `list_storage_types` | Storage volume types with recommendation |
| `list_datastores` | Datastores for a cloud (VMware) |
| `debug_storage_types` | Dump all storage types for debugging |

### Provisioning
| Tool | Description |
|------|-------------|
| `provision_vm` | Provision a VM with confirmed parameters |
| `provision_vm_with_script` | Provision + auto-run a script post-provision |

### Instances
| Tool | Description |
|------|-------------|
| `list_instances` | List instances with optional filters |
| `get_instance` | Instance details, IP, naming policy info |
| `stop_instance` | Stop a running instance |
| `start_instance` | Start a stopped instance |
| `restart_instance` | Restart an instance |
| `delete_instance` | Deprovision an instance |
| `get_instance_history` | Provisioning steps, task runs, error logs |
| `get_process_output` | Full output for a specific execution |

### Virtual Images
| Tool | Description |
|------|-------------|
| `list_virtual_images` | List registered virtual images |
| `get_virtual_image` | Image details and status |
| `register_image_from_url` | Register an image from a URL |
| `delete_virtual_image` | Remove a virtual image |

### Automation
| Tool | Description |
|------|-------------|
| `list_tasks` | List tasks in the automation library |
| `list_workflows` | List workflows |
| `get_workflow` | Workflow details and tasks |
| `create_shell_script_task` | Create a bash script task |
| `create_operational_workflow` | Create an on-demand workflow |
| `create_provisioning_workflow` | Create a lifecycle workflow |
| `execute_task_on_instance` | Run a task on a running instance |
| `run_task_on_server` | Run a task on a server |
| `run_workflow_on_instance` | Execute a workflow on an instance |
| `delete_task` | Delete a task |
| `delete_workflow` | Delete a workflow |
| `list_processes` | View execution history |

### Service Catalog
| Tool | Description |
|------|-------------|
| `list_catalog_items` | List catalog item types |
| `get_catalog_item` | Catalog item details |
| `create_catalog_item` | Create a catalog item |
| `delete_catalog_item` | Delete a catalog item |
| `list_catalog_types` | List orderable catalog types |
| `get_catalog_type` | Catalog type with input fields |
| `order_catalog_item` | Order/deploy a catalog item |
| `list_catalog_orders` | List catalog orders |
| `get_catalog_order` | Order details |
| `list_blueprints` | List blueprints |
| `get_blueprint` | Blueprint details |
| `create_blueprint` | Create a blueprint |
| `delete_blueprint` | Delete a blueprint |

### Tenants, Roles & Users
| Tool | Description |
|------|-------------|
| `list_tenants` | List all tenants (fully paginated) |
| `get_tenant` | Tenant details |
| `create_tenant` | Create a sub-tenant |
| `delete_tenant` | Delete a tenant |
| `list_roles` | List all roles |
| `get_role` | Role details |
| `create_role` | Create a role |
| `delete_role` | Delete a role |
| `list_users` | All users — paginated, searchable |
| `get_user` | User details |
| `create_user` | Create a user with role assignment |
| `delete_user` | Delete a user |

### License & Reporting
| Tool | Description |
|------|-------------|
| `get_license` | License tier, limits, usage, expiry |
| `validate_release` | Parse release notes, run automated API tests |