cli-wrap-mcp

Turn any CLI into an MCP server with a declarative YAML config.

cli-wrap-mcp is a small engine that reads a YAML file describing a set of tools (each tool = one argv template + typed, validated parameters) and serves them as an MCP stdio server. No code generation, no per-tool server projects — one config file per server.

server:
  name: gh-explorer
  description: Read-only GitHub exploration tools.

tools:
  - name: pr_view
    description: Show a pull request.
    argv: ["gh", "pr", "view", "{number}", "--repo", "{repo}", "--json", "title,body,state"]
    params:
      number:
        type: integer
        description: PR number.
      repo:
        type: string
        description: Repository in owner/name form.
        pattern: "[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+"

Why

Giving an agent raw shell access means permissioning at the granularity of "can run commands". Wrapping a CLI as an MCP server flips that: the agent sees a small set of narrow, typed, validated tools, and you manage permissions per MCP server / per tool. A config file is all it takes to mint a new server, so each domain (GitHub exploration, build tooling, ...) can ship its own MCP definition without owning any engine code.

Related MCP server: MCP-Ables

Safety design

Safety is the core of this engine, enforced at execution and load time:

• No shell, ever. Commands run as argv arrays with shell=False. There is no code path that concatenates a shell string, so ; rm -rf /, $(...), pipes etc. stay inert single arguments.

• Validation before interpolation. Every parameter value must pass its type check, pattern (regex fullmatch), and enum before it is rendered into argv.

• Argument-injection guard. Rendered values starting with - are rejected by default, so a model cannot smuggle --force-style flags into a positional slot. Opt out per parameter with allow_dash_prefix: true.

• Strict placeholders. {param} only — format specs, conversions, attribute or index access ({p.__class__}) are load-time errors, as are placeholders that reference undefined parameters.

• stdout is protocol-only. The MCP stdio channel is never polluted; all engine logging goes to stderr.

• Bounded output. Inline tool output is truncated at inline_max_output_bytes by default; inline_on_large_output: file diverts oversized output to a file (path plus head/tail excerpts), and output_mode: file always writes the full output to a file — success or failure — for audit-trail use. Callers can also pass the auto-injected file_output_dir parameter to force the full output into a directory of their choosing.

• Job isolation. Background job IDs are strictly format-checked, blocking path traversal through job_id.

• Guardrails, not a sandbox. For "arbitrary subcommand" tools (an array param with allow_dash_prefix: true), deny_pattern, forced trailing flags, and env forcing constrain what the model can do — but a determined CLI often has more than one spelling for the same effect. Treat them as accident prevention and put the real security boundary in the credentials the wrapped CLI runs with (see examples/gcloud.yml).

Trust model: the YAML config is a trusted local file (it decides which binaries can run); the tool arguments coming from the model are untrusted and constrained as above. The wrapped CLI runs with your local privileges.

Install / run

Requires Python >= 3.11. With uv:

uvx cli-wrap-mcp@0.1.0 --config /path/to/config.yml

Or straight from git (pin a tag, or a commit SHA for full immutability):

uvx --from git+https://github.com/hkak03key/cli-wrap-mcp@v0.1.0 cli-wrap-mcp --config /path/to/config.yml
uvx --from git+https://github.com/hkak03key/cli-wrap-mcp@<commit-sha> cli-wrap-mcp --config /path/to/config.yml

Try the bundled examples:

uvx cli-wrap-mcp@0.1.0 --config examples/echo.yml

examples/gcloud.yml shows the "arbitrary subcommand with forced env vars and options" pattern (variadic array param + deny_pattern + env forcing).

Claude Code

Project .mcp.json:

{
  "mcpServers": {
    "echo-demo": {
      "command": "uvx",
      "args": ["cli-wrap-mcp@0.1.0", "--config", "./configs/echo.yml"]
    }
  }
}

From a Claude Code plugin, ship only your configs and reference them via ${CLAUDE_PLUGIN_ROOT}:

{
  "mcpServers": {
    "gh-explorer": {
      "command": "uvx",
      "args": ["cli-wrap-mcp@0.1.0", "--config", "${CLAUDE_PLUGIN_ROOT}/configs/gh-explorer.yml"]
    }
  }
}

Config reference

Top level:

Per tool:

Per parameter (params.<name>):

Array (variadic) parameters

type: array accepts a list of strings and expands into that many argv elements — use it to pass a variable-length subcommand tail (gcloud {args}). Rules:

• The placeholder must be an entire argv element ("{args}"); embedding it in a larger element ("--x={args}") is a load-time error, because the expansion would collapse into one element and change meaning.

• pattern, deny_pattern, enum, and the dash-prefix guard are applied to each item individually; every item stays exactly one argv element (no shell, no word splitting).

• An empty list expands to zero elements. Optional arrays default to [] unless an explicit default is given.

• Fixed argv elements placed after the placeholder still apply, which lets a config force trailing flags that override anything the model passed earlier (for argparse-style CLIs the last occurrence of a flag wins).

Parameter names must match [a-z_][a-z0-9_]* and must not be Python keywords. file_output_dir is reserved: the engine injects it into every sync tool as an optional absolute-path parameter; when set, the full output is always written under that directory — regardless of size, exit code, or the tool's output_mode — and only the file path plus excerpts are returned. It overrides the config-level file_output_dir for that call.

File output layout

Every file output is a per-invocation directory (same layout as job dirs):

<root>/outputs/<tool>-<timestamp>-<id>/
  stdout.log   # full stdout
  stderr.log   # full stderr
  meta.json    # tool, argv, started_at, exit_code (timed_out on timeout)
<root>/jobs/<job_id>/
  stdout.log  stderr.log  meta.json  pid  exit_code

meta.json records what was executed, so a file-mode tool leaves a self-contained audit trail: what ran, when, what it printed (including failures and timeouts, best-effort). <root> resolution: per-call file_output_dir param > tool file_output_dir > defaults.file_output_dir > ~/.cache/cli-mcp/<server>/ (override the cache location with CLI_MCP_CACHE_DIR).

Job mode

mode: job wraps long-running commands. Instead of one tool, four are exposed:

• <name>_start — starts the command detached (own process group), returns a job_id

• <name>_status — running/exited state plus stdout/stderr tails

• <name>_result — final output (tail-limited by inline_max_output_bytes)

• <name>_cancel — SIGTERM to the whole process group

Job logs and metadata persist under <root>/jobs/ (the tool's file_output_dir, or the cache dir), so finished jobs remain inspectable (best-effort) even across server restarts. See examples/sleep-job.yml.

Development

uv sync
uv run pytest

Releases are published to PyPI via GitHub Releases using Trusted Publishing (OIDC, no API tokens) — see .github/workflows/publish.yml.

License

MIT