MCP CLI Wrapper

A flexible MCP (Model Context Protocol) server that wraps any CLI tool and exposes its subcommands as individual MCP tools with typed parameters.

Features

Config-driven tools: Define CLI subcommands as MCP tools via JSON configuration
Fallback mode: Single run_cli tool when no config provided
Type-safe parameters: Zod validation for all inputs before execution
Flexible parameter types: Supports positional args, flags, and boolean switches
Preserved parameter order: Flags and positionals stay interleaved as defined
Nested subcommands: Supports git remote add style commands
Safe execution: Uses spawnSync to prevent command injection
Full output capture: Returns stdout, stderr, and exit code

Installation

npm install npm run build

Usage

Basic (Fallback Mode)

Run without a config file to get a single run_cli tool that accepts raw arguments:

node dist/index.js git

This exposes one tool:

run_cli - Accepts args: string[] and executes git <args...>

With Configuration

Run with a config file to expose multiple typed tools:

node dist/index.js git ./config.example.json

This exposes tools like:

git_status - Show working tree status
git_commit - Commit with typed message and optional all flag
git_add - Stage files with pathspec parameter
git_log - Show logs with oneline and max_count options
And more...

Configuration Format

Create a JSON file with tool definitions:

{ "tools": [ { "name": "git_commit", "description": "Record changes to the repository with a commit message.", "subcommand": "commit", "parameters": [ { "name": "message", "type": "string", "description": "The commit message.", "flag": "-m", "required": true }, { "name": "all", "type": "boolean", "description": "Automatically stage all modified files.", "flag": "--all", "required": false } ] } ] }

Parameter Configuration

Each parameter supports:

Field	Type	Description
`name`	string	Parameter name (used in schema)
`type`	`"string"` \| `"number"` \| `"boolean"`	Parameter type
`description`	string	Description shown to AI agents
`flag`	string (optional)	CLI flag (e.g., `-m` , `--force` ). If omitted, parameter is positional
`required`	boolean	Whether the parameter is required

Parameter Order

Parameters are processed in declaration order. This allows you to define tools where flags must precede positional arguments:

{ "name": "docker_run", "subcommand": "run", "parameters": [ { "name": "interactive", "flag": "-it", "type": "boolean", "required": false }, { "name": "image", "type": "string", "required": true }, { "name": "command", "type": "string", "required": false } ] }

This produces: docker run -it ubuntu bash (flags before positionals)

Nested Subcommands

Use spaces in subcommand for nested commands:

{ "name": "git_remote_add", "subcommand": "remote add", "parameters": [ { "name": "name", "type": "string", "required": true }, { "name": "url", "type": "string", "required": true } ] }

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{ "mcpServers": { "git": { "command": "node", "args": ["/path/to/mcp-cli-wrapper/dist/index.js", "git", "/path/to/config.json"] } } }

Claude Code

Add to your MCP settings:

{ "mcpServers": { "git": { "command": "node", "args": ["./dist/index.js", "git", "./config.example.json"] } } }

Example Configs

Git (included)

See config.example.json for a complete Git configuration with 8 tools.

Docker (example)

{ "tools": [ { "name": "docker_ps", "description": "List running containers", "subcommand": "ps", "parameters": [ { "name": "all", "type": "boolean", "flag": "-a", "description": "Show all containers", "required": false } ] }, { "name": "docker_run", "description": "Run a container", "subcommand": "run", "parameters": [ { "name": "detach", "type": "boolean", "flag": "-d", "description": "Run in background", "required": false }, { "name": "name", "type": "string", "flag": "--name", "description": "Container name", "required": false }, { "name": "image", "type": "string", "description": "Image to run", "required": true } ] } ] }

Security

No shell interpolation: Arguments are passed directly via spawnSync, preventing command injection
Input validation: All parameters validated with Zod schemas before execution
Local execution only: Commands run on the local machine with the user's permissions

Development

# Install dependencies npm install # Build npm run build # Run in development npm run dev git ./config.example.json

License

MIT

MCP CLI Wrapper

MCP CLI Wrapper

Features

Installation

Usage

Basic (Fallback Mode)

With Configuration

Configuration Format

Parameter Configuration

Parameter Order

Nested Subcommands

MCP Client Configuration

Claude Desktop

Claude Code

Example Configs

Git (included)

Docker (example)

Security

Development

License

Related Resources

New MCP Servers

MCP directory API