# VeryCloud MCP

Manage a VeryCloud/Wisp game server from ChatGPT, Claude, Cursor, or another MCP client.

Supports server status, files and logs, console commands, power controls, audit logs, and backups. Your VeryCloud API token stays on the MCP host.

## Install

Requires Python 3.11+ and a VeryCloud API token.

```bash
git clone https://github.com/BreezeDelegate/verycloud-mcp.git
cd verycloud-mcp
python -m venv .venv
```

Windows PowerShell:

```powershell
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
Copy-Item .env.example .env
```

Linux/macOS:

```bash
source .venv/bin/activate
python -m pip install -e .
cp .env.example .env
```

Set these two values in `.env`:

```env
VERYCLOUD_API_TOKEN=your_verycloud_api_token
VERYCLOUD_SERVER_ID=your_server_id
```

Then:

```bash
verycloud-mcp --check
verycloud-mcp
```

Local MCP URL: `http://127.0.0.1:8000/mcp`

## Connect

### ChatGPT: private/local test with Secure MCP Tunnel

This is the recommended first real-world test because the MCP server remains bound to localhost and does not need a public inbound port.

1. In OpenAI Platform, create a Secure MCP Tunnel and a separate runtime API key with the required tunnel permissions.
2. Put the values in your local `.env` only:

```env
CONTROL_PLANE_TUNNEL_ID=tunnel_...
CONTROL_PLANE_API_KEY=your_runtime_api_key
```

3. Install the official OpenAI `tunnel-client` and ensure `tunnel-client` is available in your `PATH`.
4. Start VeryCloud MCP and the tunnel together:

Windows PowerShell:

```powershell
.\scripts\run-chatgpt-tunnel.ps1
```

Linux/macOS:

```bash
chmod +x scripts/run-chatgpt-tunnel.sh
./scripts/run-chatgpt-tunnel.sh
```

5. In ChatGPT Developer Mode, create a custom app, choose **Tunnel** as the connection type, select the tunnel, scan the tools, and test the draft app.

Official OpenAI tunnel documentation: `https://developers.openai.com/api/docs/guides/secure-mcp-tunnels`

Never paste the VeryCloud API token or OpenAI runtime API key into chat, issues, commits, or screenshots.

### Claude Code

```bash
claude mcp add --transport http verycloud http://127.0.0.1:8000/mcp
```

For a remote instance protected with `VERYCLOUD_MCP_AUTH_TOKEN`:

```bash
claude mcp add --transport http verycloud https://mcp.example.com/mcp --header "Authorization: Bearer your_mcp_token"
```

### Cursor

Add the MCP URL as a Streamable HTTP server in Cursor's MCP settings. Project configs live in `.cursor/mcp.json`; global configs live in `~/.cursor/mcp.json`.

## Allow changes

Write actions are off by default. Enable only what you want in `.env`:

```env
VERYCLOUD_ALLOW_COMMANDS=true
VERYCLOUD_ALLOW_FILE_WRITES=true
VERYCLOUD_ALLOW_POWER=true
VERYCLOUD_ALLOW_BACKUPS=true
VERYCLOUD_ALLOW_DESTRUCTIVE=false
```

`VERYCLOUD_ALLOW_DESTRUCTIVE=true` is additionally required for file deletion, backup restore/delete, and force-kill.

## Remote / Docker

For a remote listener:

```env
VERYCLOUD_MCP_HOST=0.0.0.0
VERYCLOUD_MCP_AUTH_TOKEN=use_a_long_random_token_here
VERYCLOUD_MCP_ALLOWED_HOSTS=mcp.example.com,mcp.example.com:443
```

Put HTTPS in front of the MCP server. `VERYCLOUD_MCP_AUTH_TOKEN` protects the MCP endpoint; it is not your VeryCloud token.

```bash
docker build -t verycloud-mcp .
docker run --rm -p 8000:8000 --env-file .env -e VERYCLOUD_MCP_HOST=0.0.0.0 verycloud-mcp
```

Never commit `.env` or any token. Non-commercial use only; see `LICENSE`. Contributions: `CONTRIBUTING.md`.