cubox-mcp-cli

A generic pass-through MCP server for the official cubox-cli. It exposes exactly one tool, cubox_cli, whose canonical parameter is args: string[] — the argv you would type after cubox-cli on the command line. It also tolerates clients that serialize the array as a string or wrap it in one or more { "item": ... } objects. When Cubox adds, renames, or removes commands, this wrapper does not need to change.

What is this?

This is a Model Context Protocol (MCP) server that wraps the official Cubox CLI. Instead of hard-coding Cubox's command surface, it forwards the argument array straight to cubox-cli and returns the output. It also includes a shallow, fail-safe guard against destructive operations (delete/remove/rm without a force/confirm flag).

Why fork/use this?

• Future-proof: cubox-cli can change its commands and flags anytime; this server stays the same.
• One tool for everything: cubox_cli({ args: ["--help"] }) works for any command.
• No npm account required: run directly from GitHub with npx.
• Works with any MCP client: tested with mcphub, Claude Desktop, and the MCP Inspector.
• Optional container: ships with a Dockerfile and a Docker Compose template for HTTP transport.

Quick start

1. Get a Cubox API token

The Cubox backend uses a static API Extension link rather than OAuth, so you log in once and copy the link:

npx -y cubox-cli auth login
# → open https://cubox.pro/web/settings/extensions, enable the API Extension,
#   copy the unique link, and paste it back at the prompt

This writes ~/.config/cubox-cli/config.json on the machine where you run it. If your MCP client runs elsewhere, you will need to pass CUBOX_TOKEN as an environment variable (see below).

2. Add to your MCP client

No clone or local install is needed for the host running the MCP client. npx will pull the code from GitHub and install dependencies automatically.

mcphub mcp_settings.json:

{
  "mcpServers": {
    "cubox": {
      "command": "npx",
      "args": ["-y", "github:Lascivea/cubox-mcp-cli"],
      "env": {
        "CUBOX_TOKEN": "your_token",
        "CUBOX_SERVER": "cubox.pro"
      }
    }
  }
}

Claude Desktop / other clients: use the same npx command and environment variables.

3. Test it

Call the tool with:

{ "args": ["--help"] }

For compatibility with some function-calling clients, these equivalent forms are also accepted:

{ "args": "--help" }
{ "args": { "item": ["--help"] } }
{ "args": { "item": { "item": ["card", "list"] } } }

The canonical form remains an array of strings. The wrapper unwraps the compatibility forms before applying safety checks and invoking cubox-cli.

Or try a read-only command like:

{ "args": ["folder", "list"] }

Configuration example

Variable	Required	Default	Notes
CUBOX_TOKEN	yes*	—	The last segment of your Cubox API Extension link (e.g. abcd12345). Required when the MCP host is a different machine than the one where you ran cubox-cli auth login.
CUBOX_SERVER	no	cubox.pro	Cubox server domain. Use cubox.cc for the international instance.
CUBOX_CLI_BIN	no	auto	Override the cubox-cli binary path. By default the wrapper resolves node_modules/.bin/cubox-cli, then falls back to PATH.
MCP_TRANSPORT	no	stdio	stdio for mcphub / Claude Desktop / local clients. http for the standalone Docker container.
PORT	no	3000	Only used when MCP_TRANSPORT=http.

No credentials are baked into the image or written to disk by this wrapper. CUBOX_TOKEN and CUBOX_SERVER are read by cubox-cli itself, not by this server.

Docker Compose deployment

Copy the template and edit the environment variables:

cp docker-compose.example.yaml docker-compose.yaml
# edit docker-compose.yaml, set CUBOX_TOKEN
docker compose up -d

The container runs the MCP server over HTTP on port 3000. Register it in your MCP client with a url entry pointing at http://localhost:3000/mcp.

Local development

cd cubox-mcp-cli
npm install
node test-client.js          # regression tests against fake-cubox-cli.sh
npm run inspector            # interactive MCP Inspector

Design notes

Why only one tool?

A single { args: string[] } schema is the canonical interface and keeps command discovery simple. At runtime, a preprocessing layer also accepts the common array-serialization quirks produced by some function-calling clients: a string, { item: ... }, or nested { item: ... } wrappers. Agents can discover commands live by calling cubox_cli({ args: ["--help"] }) or cubox_cli({ args: ["card", "--help"] }).

What is hard-coded?

• The global -o json flag, with a fallback to plain text if a sub-command rejects it.
• A shallow guard against destructive operations: any call containing delete/remove/rm must also contain --force, --yes, -y, or --confirm. If Cubox renames its delete command, this guard simply stops matching — it never blocks something new incorrectly.

Upgrading cubox-cli later

Nothing to do. npx resolves the dependency fresh from package.json whenever the cache is rebuilt. To force a refresh: npx clear-npx-cache or bump the cubox-cli version range in package.json.

Companion projects / related tools

• cubox-cli — the official Cubox CLI this server wraps.
• mcphub — an MCP server manager that pairs well with this project.

License

MIT