cubox-mcp

cubox-mcp

A generic pass-through MCP server for the official cubox-cli. It exposesexactly one tool, cubox_cli, whose only parameter is args: string[] —the argv you'd type after cubox-cli on the command line. Everything theCLI 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. Nonpm 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 runsit 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 onestep (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 elseinside it):

git clone [email protected]: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 — theCLI parses the server and token out of it itself. This writes~/.config/cubox-cli/config.json, which persists — you only do this onceper machine.

There's no further automation possible here: unlike some MCP servers(e.g. Craft's), Cubox's backend doesn't expose an OAuth authorizationserver, only this static extension-link flow, so a "click to approve inbrowser" 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 [email protected]: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/reposhorthand, clones it, runs npm install inside the clone (which pulls incubox-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 workunauthenticated. For a private repo, whatever host runs npx needs its owngit credentials configured (SSH key or a stored token) so the clonesucceeds non-interactively.

Environment variables

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

CUBOX_TOKEN and CUBOX_SERVER are read by the bundled cubox-cliitself, not by this wrapper — this MCP server has no idea what they mean,it just passes environment through to the spawned child process like anyparent 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 cachemiss), the name cubox-mcp is currently unclaimed:

npm login
npm publish

npm pack --dry-run from this folder confirms the published tarball wouldbe just index.js + package.json + README.md (~5 kB) — the filesfield in package.json excludes the dev-only test scaffolding. Notrequired 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 possibleJSON Schema shape, which sidesteps client-side schema-validation quirkssome MCP clients have with anyOf/oneOf/nested-object tool schemas.
• Agents that don't know the current command surface can just callcubox_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 givensub-command rejects it.
• A shallow, syntactic guard against destructive operations: any call whoseargs contains delete/remove/rm is blocked unless it also containsa force/confirm flag (--force, --yes, -y, --confirm). This failssafe — if cubox-cli ever renames its delete command, the guard simplystops matching (delete calls pass straight through), it never startsblocking something new incorrectly.

Upgrading cubox-cli later

Nothing to do — npx resolves cubox-mcp's dependency on cubox-clifresh from its declared version range each time the npx cache is rebuilt.To force an immediate refresh: npx clear-npx-cache (or just bump thecubox-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 aNode process at all, Dockerfile + entrypoint.sh in this repo package thesame server behind a Streamable HTTP endpoint (MCP_TRANSPORT=http) thatyou register via a url entry instead of command/args. Most peoplewon't need this — the npx setup above is simpler and works for thecommon case.