Skip to main content
Glama
Sign In
arcane-cli-mcp

arcane-cli-mcp

by joshnewman17
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

arcane_run

Destructive

Execute arcane-cli commands against an Arcane instance and return JSON results, with confirmation prompts and filters for safe Docker homelab inspection and management.

Instructions

Run an arcane-cli command against the Arcane instance and return its JSON output.

args is the command and its arguments WITHOUT the binary name. The server adds --json, --env <env_id> (for environment-scoped commands) and, only when confirm=true, --yes. Any --yes/-y/--force/--json/ --output you pass is stripped. Use env_id (an id or an environment name such as "homelab") instead of --env. Flags that read local files (--file, --env-file, ...) are rejected: to create a project use arcane_project_create, to change its compose file arcane_project_compose. --help is answered as by arcane_cli_help.

Result: {ok, exit_code, data, error, stderr_tail, command}. On failure error holds the CLI's message. List commands return {data, pagination}; use --limit/--start or filters when output is truncated (--all cannot be combined with --limit). With compact=true (default):

  • list commands for containers, projects, images, volumes, networks, activities and vulnerabilities return one short summary per item (name, image, state, health, project, ports, hasUpdate, ...). A container whose image is only a sha256 id has image_untagged=true: Arcane can't check it for updates.

  • activities list folds consecutive identical entries into one with repeated/firstAt/lastAt.

  • volumes sizes returns a summary plus the largest named and anonymous volumes; jobs list returns {id, name, enabled, schedule, nextRun, lastRun, currentRun, unmetPrerequisites} per job; containers get drops image-metadata labels (org.opencontainers.*, ...). Pass compact=false for the full objects.

Filters, applied by the server to the items the CLI returned (use --all so they see every page): filter_state (e.g. running, exited, created), filter_has_update, filter_project, name_contains. exclude_types (activities list only), e.g. ["job_run", "image_update_check"], drops noisy activity types and with it --limit N (default 20) is the number of rows returned, after excluding and folding repeats (the server fetches more activities to fill them).

Streaming commands (projects up/redeploy/pull/build, images pull/build, containers update) can take up to 30 minutes and return an array of progress frames when done.

If the result has needs_confirmation=true, NOTHING was changed: show the user the command and ask. Retry with confirm=true only after they approve. Blocked commands fail even with confirm=true. If the result has self_target=true, the command would restart this MCP server itself (its own project or containers) and the call would drop. Suggest the Arcane UI; only if the user explicitly insists, retry with confirm=true and allow_self=true.

To know whether a newer Arcane exists, use version (updateAvailable). system upgrade --check reports canUpgrade, which only means the upgrade mechanism works.

Examples:

  • {"args": ["containers", "list", "--all"], "filter_has_update": true}

  • {"args": ["containers", "updates"], "env_id": "homelab"}

  • {"args": ["projects", "redeploy", "immich"], "env_id": "0"}

  • {"args": ["projects", "destroy", "old-stack", "--remove-files=false"], "confirm": true} (only after the user explicitly approved this exact command)

  • {"args": ["activities", "list", "--status", "failed", "--limit", "10"], "exclude_types": ["job_run"]}

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "args": "<args>"
    },
    "name": "arcane_run"
  }
}

Input Schema

NameRequiredDescriptionDefault
argsYes
env_idNo
compactNo
confirmNo
allow_selfNo
filter_stateNo
exclude_typesNo
name_containsNo
filter_projectNo
filter_has_updateNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond destructiveHint=true: documents arg rewriting and stripping of --yes/--json, rejection of local-file flags, the needs_confirmation gate that means nothing changed, blocked commands failing even with confirm, self_target restart hazard, and streaming commands taking up to 30 minutes and returning progress frames.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Long but well partitioned into arg handling, result shape, compact mode, filters, streaming, confirmation, and examples; every block carries decision-relevant information. Slightly dense in the compact-mode bullet list, which costs a bit of scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

A 10-parameter command wrapper with high destructive potential is fully covered: invocation contract, safety gates, output envelope, pagination, truncation and the confirm/allow_self escalation path are all present, despite an output schema also existing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry the parameter burden and it does: args format (no binary name), env_id accepting an id or a name like 'homelab', compact true/false effects per command family, filter_* semantics applied server-side to CLI-returned items, exclude_types scope to activities list, and the --all interaction.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Run an arcane-cli command against the Arcane instance') and its return shape, and explicitly differentiates from siblings by naming arcane_project_create, arcane_project_compose and arcane_cli_help for the cases that would otherwise look like plain CLI runs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing rules: use env_id rather than --env, use arcane_project_create instead of file-reading flags, confirm=true only after user approval, allow_self=true only on explicit insistence, compact=false for full objects, and --all together with server-side filters.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools