oneclickvirt
GitHub管理OneClickVirt容器和虚拟机实例、提供商节点及系统健康检查的AI辅助技能,支持通过MCP进行日常运维与故障排查。
触发场景
安装
npx skills add oneclickvirt/oneclickvirt --skill oneclickvirt -g -y
SKILL.md
Frontmatter
{
"name": "oneclickvirt",
"metadata": {
"author": "oneclickvirt",
"version": "0.3.0",
"homepage": "https:\/\/github.com\/oneclickvirt\/oneclickvirt"
},
"description": "OneClickVirt operations skill for managing containers, virtual machines, provider nodes, health checks, and metrics through MCP."
}
OneClickVirt Skill
Overview
This skill helps an AI assistant operate a OneClickVirt deployment through the built-in MCP server. It is useful for routine instance management, provider inspection, platform health checks, and guided troubleshooting.
What this skill can do:
- List, create, start, stop, restart, inspect, and delete instances.
- List providers and run provider health checks.
- Read system status, health, configuration, and monitoring resources.
- Use prompt templates for common container, VM, status, and troubleshooting workflows.
Prerequisites
- Python 3.9+ for the installer. Prebuilt MCP binaries support Linux/Windows amd64 and ARM64; other platforms can use an existing binary or SSH transport.
- A running OneClickVirt API endpoint.
- An administrator API token from the Web UI under Profile -> API Tokens.
- HTTPS for remote OneClickVirt deployments.
Installation
Install or update the latest stable release from GitHub:
curl -fL --retry 3 https://raw.githubusercontent.com/oneclickvirt/oneclickvirt/main/scripts/install_skill.py -o install_skill.py
python3 install_skill.py --client claude
The same installer is available from the CNB public source mirror:
curl -fL --retry 3 https://cnb.cool/oneclickvirt/oneclickvirt/-/git/raw/main/scripts/install_skill.py -o install_skill.py
python3 install_skill.py --client claude
Choose --client codex or --client openclaw for those clients. The default directories are ~/.claude/skills/oneclickvirt, ~/.agents/skills/oneclickvirt, and ~/.openclaw/skills/oneclickvirt; --skill-dir overrides the destination. On Windows, download the same script and run it with Python 3.9+ (py -3 install_skill.py --client claude).
Both entry points resolve one published GitHub Release, verify its Skill and binary checksums, and install them together. CNB mirrors source; these release archives are downloaded from GitHub. The installer creates SKILL.md directly in the Skill directory and a separate oneclickvirt-mcp binary in ~/.local/bin. It does not start the controller or alter services, databases, client settings, or existing API tokens.
Repeat the download and installation commands to update. Pass --version with an exact published tag to pin a release or return to it; the Skill and binary use that same tag. install.json records the installed version. Reuse an existing controller binary with --mcp-command /opt/oneclickvirt/server/oneclickvirt-server, or use --skip-binary to install only the Skill files. A Skill alone does not configure or start MCP.
The installer generates mcp.codex.toml for ~/.codex/config.toml, mcp.claude.json for the project .mcp.json, and mcp.openclaw.json for ~/.openclaw/openclaw.json. Merge the matching file while keeping existing entries, retain the absolute binary path, and set your API URL/token. mcp.example.json remains a Claude-format compatibility example. The Claude Code structure is:
{
"mcpServers": {
"oneclickvirt": {
"command": "oneclickvirt-mcp",
"args": ["mcp"],
"env": {
"ONE_CLICK_VIRT_API_URL": "https://your-domain.com",
"ONE_CLICK_VIRT_API_TOKEN": "YOUR_API_TOKEN"
}
}
}
}
The command must be visible to the MCP client; GUI clients may not inherit your shell's PATH. A controller installed by the project uses /opt/oneclickvirt/server/oneclickvirt-server, not /opt/oneclickvirt/server/oneclickvirt. macOS has no prebuilt controller asset: use --skip-binary and configure an existing native build or an SSH MCP transport to Linux. Restart the MCP client after configuration. See the installation guide for release archives and SSH examples.
Usage
Available MCP tools:
list_instances— List all virtual machine and container instances in OneClickVirtcreate_instance— Create a new virtual machine or container instancestart_instance— Start a stopped instancestop_instance— Stop a running instancerestart_instance— Restart an instancedelete_instance— Delete an instance (DANGER: irreversible)get_instance_detail— Get detailed information about a specific instancelist_providers— List all virtualization provider nodeshealth_check— Run a health check on a provider nodeget_instance_logs— Get recent logs from an instanceget_system_status— Get overall system status including instance counts and resource usageget_metrics— Get monitoring metrics for the system, a provider, or an instance
Available resources:
oneclickvirt://instances/list— Current list of all instancesoneclickvirt://providers/list— Current list of all provider nodesoneclickvirt://system/status— Overall system health and metricsoneclickvirt://health/status— Public OneClickVirt API health statusoneclickvirt://config/system— Administrator-visible system configuration
Available prompt templates:
create_debian_container— Template for creating a Debian Linux containercreate_ubuntu_vm— Template for creating an Ubuntu virtual machinetroubleshoot_instance— Template for troubleshooting an instance that won't startquick_status_check— Template for checking instance, provider, and platform health
Examples
- "List running instances and summarize anything frozen or stopped."
- "Create a Debian 12 container on provider 1 with 2 CPU, 1 GB memory, and 20 GB disk."
- "Run a quick status check for the platform."
- "Check provider 3 health and summarize capacity concerns."
- "Troubleshoot instance 42 and suggest the safest next action."
Troubleshooting
command not found: oneclickvirt-mcp: use the absolute command path from the installedmcp.example.jsonin the client config.401 Unauthorized: verifyONE_CLICK_VIRT_API_TOKENis an active administrator token.Connection refused: verifyONE_CLICK_VIRT_API_URLand that/api/v1/healthis reachable.- Tools do not appear: restart the MCP client and inspect its MCP server logs.
Security
- Prefer environment variables over command-line token arguments.
- Use a dedicated token with the minimum required permissions.
- Review destructive requests such as
delete_instancebefore confirming. - Use HTTPS for remote API endpoints.
版本历史
-
6935665
当前 2026-11-02 16:58
新增自动化安装脚本以支持多客户端配置生成;增加Windows原生MCP安装测试;修复发布版本技能包验证问题。
- 44ad6a5 2026-07-05 20:22


