Skip to main content
Glama
cubox-mcp

cubox-mcp

by Huakira

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).

Related MCP server: Obsidian MCP Server

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.

  • cubox-cli — the official Cubox CLI this server wraps.

  • mcphub — an MCP server manager that pairs well with this project.

License

MIT

Available Tools

1 tool
cubox_cliCubox CLIA

Run any cubox-cli command and get its JSON output back. This is a thin, generic pass-through — it does not enumerate Cubox's capabilities itself. If you don't know what's available, first call this tool with args: ['--help'], or args: ['', '--help'] (e.g. ['card', '--help']) to discover current sub-commands and flags directly from the CLI, since they may change over time. Example: args: ['card', 'list', '--folder', 'Reading'] lists cards in a folder. Destructive operations (delete/remove) are blocked unless a force/confirm flag is included in args — call once without it to see a dry-run / confirmation prompt, then call again with the force flag the CLI reports (e.g. --force) once you've confirmed the target is correct.

Inputs: args (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 1 tool

    Disambiguation5/5

    With only a single tool, there is no possibility of confusion between tools. The tool's description clearly states its purpose as a generic CLI pass-through, leaving no room for ambiguity.

    Naming Consistency5/5

    A single tool inherently follows a consistent naming pattern. The name 'cubox_cli' is clear and matches the server's purpose, so there are no inconsistencies to penalize.

    Tool Count3/5

    One tool is at the low end of typical server scopes, but it acts as a general-purpose gateway to the entire Cubox CLI. This can be seen as minimalistic yet functional, though it may feel thin compared to more structured multi-tool servers.

    Completeness5/5

    The generic pass-through tool allows access to all cubox-cli commands, including destructive operations with safeguards. Agents can discover and execute any CLI command, making the tool surface complete for the targeted domain.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      C
      maintenance
      Wraps the cursor-agent CLI to provide cost-effective tools for repository analysis, code search, planning, and editing. Offloads heavy thinking tasks from the host AI to reduce token usage while maintaining precise, scoped workspace operations.
      7
      5 npm
      MIT
    • F
      license
      C
      quality
      D
      maintenance
      Provides LLM agents with comprehensive access to Obsidian vaults via the official Obsidian CLI bridge. It enables users to read, search, and modify notes, tasks, properties, and plugins while the Obsidian desktop app is running.
      54
      16
      -
    • A
      license
      B
      quality
      D
      maintenance
      Wraps the Obsidian CLI to allow LLM agents to read/write notes, search, manage frontmatter, navigate links, and run plugins on a running Obsidian instance.
      34
      2
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables interaction with Obsidian vaults through the official Obsidian CLI, allowing note management, search, and vault operations without plugins or API keys.
      21
      MIT