cubox-mcp

A generic pass-through MCP server for the official cubox-cli. It exposes exactly one tool, cubox_cli, whose only parameter is args: string[] — the argv you'd type after cubox-cli on the command line. Everything the CLI can do, this MCP can do, forever, without code changes here.

Setup — no clone needed

Push this repo to GitHub, then the entire setup is a config entry. No npm publish, no npm account, no manual npm install step of your own — npx clones, installs, and runs it in one shot (and caches the result).

1. Log in once. Two ways to do this, your choice:

Zero-clone version — cubox-cli is itself an npm package, so npx runs it directly. You'll need to open the settings page yourself:

npx -y cubox-cli auth login
# → prompts you to open https://cubox.pro/web/settings/extensions,
#   enable the API Extension, copy your link, and paste it back in

Auto-open-browser version — needs the repo checked out just for this one step (there's no way to run an arbitrary script like login.js via npx <git-spec> — npx only runs a package's declared bin, nothing else inside it):

git clone git@github.com:YOUR_USERNAME/cubox-mcp.git
cd cubox-mcp && npm install
npm run login          # opens cubox.pro settings page in your browser
npm run login -- --cc  # cubox.cc (international)

Either way, you end up at the same interactive prompt: go to Extensions, enable the API Extension, copy your unique link (e.g. https://cubox.pro/c/api/save/abcd12345), paste it at the > prompt — the CLI parses the server and token out of it itself. This writes ~/.config/cubox-cli/config.json, which persists — you only do this once per machine.

There's no further automation possible here: unlike some MCP servers (e.g. Craft's), Cubox's backend doesn't expose an OAuth authorization server, only this static extension-link flow, so a "click to approve in browser" experience isn't something this wrapper can add on its own — login.js just saves you the trip to find the settings URL.

2. Push this repo to GitHub:

git remote add origin git@github.com:YOUR_USERNAME/cubox-mcp.git
git push -u origin main

3. Add it to mcphub's mcp_settings.json:

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

That's the whole integration. npx recognizes the github:user/repo shorthand, clones it, runs npm install inside the clone (which pulls in cubox-cli as a declared dependency automatically), and runs the bin entry — no separate install step, no path to remember, no folder to keep around. Verified locally end-to-end (clone → install → MCP handshake → tool call) against a local git repo standing in for GitHub.

Repo must be public for a bare github:user/repo reference to work unauthenticated. For a private repo, whatever host runs npx needs its own git credentials configured (SSH key or a stored token) so the clone succeeds non-interactively.

Environment variables

All credentials are passed in via env; nothing is baked into the image and nothing is written to disk by this wrapper.

Variable	Required	Default	Notes
CUBOX_TOKEN	yes	—	The token from your Cubox API Extension link. Open https://cubox.pro/web/settings/extensions, enable the API Extension, copy the unique link (e.g. https://cubox.pro/c/api/save/abcd12345) — the last path segment (abcd12345) is the token. Required when mcphub runs on a different machine than where you logged in interactively; without it, cubox-cli calls return unauthenticated errors.
CUBOX_SERVER	no	cubox.pro	Cubox server domain. Use cubox.pro for the China instance, cubox.cc for the international instance. Only meaningful together with CUBOX_TOKEN.
CUBOX_CLI_BIN	no	auto	Override path to the cubox-cli binary. By default this wrapper resolves node_modules/.bin/cubox-cli (installed automatically as a dependency), falling back to a PATH lookup. Set this only if you have a custom build or a non-standard install location.
MCP_TRANSPORT	no	stdio	stdio (default, for mcphub / Claude Desktop / local clients) or http (standalone Streamable HTTP server on $PORT, for containerized deployment — see "Optional: standalone container" below). mcphub uses stdio, so leave unset.
PORT	no	3000	Only used when MCP_TRANSPORT=http. Ignored under stdio.

CUBOX_TOKEN and CUBOX_SERVER are read by the bundled cubox-cli itself, not by this wrapper — this MCP server has no idea what they mean, it just passes environment through to the spawned child process like any parent process does. No tokens are logged or persisted by this wrapper.

Alternative: publish to npm instead

If you'd rather use the plain npx -y cubox-mcp form (marginally faster, since npm's registry CDN is faster than a fresh git clone on every cache miss), the name cubox-mcp is currently unclaimed:

npm login
npm publish

npm pack --dry-run from this folder confirms the published tarball would be just index.js + package.json + README.md (~5 kB) — the files field in package.json excludes the dev-only test scaffolding. Not required though; the GitHub route above works just as well.

Why one tool instead of many

• cubox-cli can add, remove, or rename sub-commands and flags any time — none of that is encoded in index.js, so nothing here goes stale.
• The single flat { args: string[] } schema is also the simplest possible JSON Schema shape, which sidesteps client-side schema-validation quirks some MCP clients have with anyOf/oneOf/nested-object tool schemas.
• Agents that don't know the current command surface can just call cubox_cli({ args: ["--help"] }) or cubox_cli({ args: ["card","--help"] }) to discover it live, the same way a human would.

What IS hard-coded (and why it's safe to be)

• The global -o json flag, with a fallback to plain-text output if a given sub-command rejects it.
• A shallow, syntactic guard against destructive operations: any call whose args contains delete/remove/rm is blocked unless it also contains a force/confirm flag (--force, --yes, -y, --confirm). This fails safe — if cubox-cli ever renames its delete command, the guard simply stops matching (delete calls pass straight through), it never starts blocking something new incorrectly.

Upgrading cubox-cli later

Nothing to do — npx resolves cubox-mcp's dependency on cubox-cli fresh from its declared version range each time the npx cache is rebuilt. To force an immediate refresh: npx clear-npx-cache (or just bump the cubox-cli version range in package.json and re-publish cubox-mcp).

Local development / testing without a real Cubox account

npm install
node test-client.js     # exercises tool-listing, pass-through, delete-guard
                         # against fake-cubox-cli.sh, no real credentials needed
npm run inspector        # interactive MCP Inspector over stdio

Optional: standalone container instead of npx

If mcphub can't reach the npm registry, or you'd rather not have it spawn a Node process at all, Dockerfile + entrypoint.sh in this repo package the same server behind a Streamable HTTP endpoint (MCP_TRANSPORT=http) that you register via a url entry instead of command/args. Most people won't need this — the npx setup above is simpler and works for the common case.