# Mcp2cli

> CLI bridge that wraps MCP servers as bash-invokable commands, recovering ~11K tokens of context window per session

- **Type:** MCP server
- **Install:** `agentstack add mcp-rodaddy-mcp2cli`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [rodaddy](https://agentstack.voostack.com/s/rodaddy)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [rodaddy](https://github.com/rodaddy)
- **Source:** https://github.com/rodaddy/mcp2cli

## Install

```sh
agentstack add mcp-rodaddy-mcp2cli
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# mcp2cli

[](https://buymeacoffee.com/rodaddy)

CLI bridge that wraps MCP (Model Context Protocol) servers as bash-invokable commands. Instead of loading all MCP tool definitions into an LLM's system prompt (~13K+ tokens permanently), agents invoke tools via bash at zero context cost.

Inspired by [Google Workspace CLI](https://github.com/googleworkspace/cli), which wrapped Google's complex APIs into simple CLI commands -- all the functionality, none of the hassle. mcp2cli does the same for MCP servers.

## Quick Start

```bash
# Install
git clone 
cd mcp2cli
bun install
bun run build        # produces dist/mcp2cli

# Bootstrap from existing Claude config
mcp2cli bootstrap    # reads ~/.claude.json mcpServers -> ~/.config/mcp2cli/services.json

# Use it
mcp2cli services                                    # list available services
mcp2cli n8n --help                                   # list tools for a service
mcp2cli n8n n8n_list_workflows --params '{}'         # invoke a tool
mcp2cli schema n8n.n8n_list_workflows                # inspect tool schema
```

For development without building:

```bash
bun run dev -- services
bun run dev -- n8n n8n_list_workflows --params '{}'
```

## Installation

**Prerequisites:** [Bun](https://bun.sh) v1.0+

```bash
git clone 
cd mcp2cli
bun install
bun run build
```

The compiled binary lands at `dist/mcp2cli`. Add it to your PATH or symlink it.

### macOS Binary Upgrades

On macOS, do not overwrite an existing compiled binary in place with `cp new dist/mcp2cli`. Replacing the contents of the same inode can invalidate the ad-hoc code signature and cause the next exec to be killed with `SIGKILL` / exit code 137.

Use a fresh inode instead:

```bash
rm dist/mcp2cli
cp /path/to/new/mcp2cli dist/mcp2cli
```

If the local UI daemon is managed by launchd, restart it after replacing the binary:

```bash
launchctl kickstart -k gui/501/com.mcp2cli.local-ui
```

The already-running daemon keeps the old inode open until restart, so this is safe to do while the daemon is live.

## Configuration

### Service Registry

mcp2cli discovers MCP servers from `~/.config/mcp2cli/services.json`:

```json
{
  "services": {
    "n8n": {
      "description": "n8n workflow automation",
      "backend": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/n8n-mcp"],
      "env": {
        "N8N_BASE_URL": "https://n8n.example.com",
        "N8N_API_KEY": "your-api-key"
      }
    },
    "homekit": {
      "description": "HomeKit smart home control",
      "backend": "stdio",
      "command": "node",
      "args": ["/path/to/homekit-mcp/dist/index.js"],
      "env": {}
    }
  }
}
```

Each service entry mirrors the Claude Desktop `mcpServers` format -- same `command`, `args`, and `env` fields.

### Bootstrap from Claude Config

If you already have MCP servers configured in `~/.claude.json`:

```bash
mcp2cli bootstrap
```

This reads your `mcpServers` entries and generates `services.json` automatically.

## Commands

### List Services

```bash
mcp2cli services
```

### List Tools for a Service

```bash
mcp2cli  --help
```

### Invoke a Tool

```bash
mcp2cli   --params ''
```

The `--params` value must be valid JSON matching the tool's input schema.

### Inspect Tool Schema

```bash
mcp2cli schema .
```

Returns the JSON Schema for the tool's input parameters -- useful for discovering required fields.

### Dry Run

```bash
mcp2cli   --params '{"query": "test"}' --dry-run
```

Validates input and shows what would be sent without executing the tool call.

### Field Filtering

```bash
mcp2cli   --params '{}' --fields "id,name,status"
```

Extracts only the specified fields from the response -- reduces output noise for scripting.

### Generate Skill Files

```bash
mcp2cli generate-skills 
```

Generates PAI skill files from MCP tool schemas, making tools discoverable by AI agents.

### Daemon Management

```bash
mcp2cli daemon status    # check if daemon is running, connection pool stats
mcp2cli daemon stop      # graceful shutdown
```

## Output Format

All responses are structured JSON on stdout. Logs go to stderr.

```json
// Success
{ "success": true, "result": { "workflows": [...] } }

// Error
{ "error": true, "code": "TOOL_ERROR", "message": "Workflow not found", "reason": "..." }
```

This makes mcp2cli composable with `jq`, pipes, and scripting:

```bash
# Get workflow names
mcp2cli n8n n8n_list_workflows --params '{}' | jq '.result.workflows[].name'

# Check for errors
mcp2cli n8n n8n_get_workflow --params '{"id": "123"}' | jq 'if .error then .message else .result end'
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Validation error (bad input, schema mismatch) |
| 2 | Auth error (missing credentials, permission denied) |
| 3 | Tool error (MCP tool returned an error) |
| 4 | Connection error (daemon unreachable, transport failure) |
| 5 | Internal error |

Use exit codes for scripting:

```bash
mcp2cli n8n n8n_get_workflow --params '{"id": "123"}' 2>/dev/null
if [ $? -eq 4 ]; then
  echo "Connection failed -- is the MCP server configured?"
fi
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `MCP2CLI_LOG_LEVEL` | `silent` | Log verbosity: `silent`, `error`, `warn`, `info`, `debug` |
| `MCP2CLI_IDLE_TIMEOUT` | `60` | Daemon idle timeout in seconds |
| `MCP2CLI_STARTUP_TIMEOUT` | `10000` | CLI wait time for daemon startup readiness in milliseconds |
| `MCP2CLI_TOOL_TIMEOUT` | `30000` | Tool call timeout in milliseconds |
| `MCP2CLI_REMOTE_REQUEST_TIMEOUT_MS` | `60000` | CLI HTTP request timeout for explicit remote daemon calls in milliseconds |
| `MCP2CLI_REMOTE_RETRIES` | `3` | Remote request attempts for explicit remote daemon calls |
| `MCP2CLI_REMOTE_FALLBACK_TIMEOUT_MS` | `10000` | CLI HTTP timeout for each `remote-local` probe before falling back to the local daemon |
| `MCP2CLI_REMOTE_FALLBACK_RETRIES` | `1` | Remote probe attempts before `remote-local` calls fall back to the local daemon |
| `MCP2CLI_POOL_MAX` | `50` | Max concurrent MCP connections in the pool |
| `MCP2CLI_LOG_DIR` | `~/.cache/mcp2cli/logs` | Directory for stderr capture logs |
| `MCP2CLI_NO_DAEMON` | (unset) | If set, bypass the daemon and connect directly |
| `MCP2CLI_DEBUG` | (unset) | If `1`, print discarded stdout lines from MCP servers |

Example:

```bash
MCP2CLI_LOG_LEVEL=debug mcp2cli n8n n8n_list_workflows --params '{}'
MCP2CLI_NO_DAEMON=1 mcp2cli n8n n8n_list_workflows --params '{}'
```

## Architecture

```
CLI Entry (src/cli/index.ts)
  |-- Command Dispatch (services, schema, bootstrap, generate-skills, daemon)
  |-- Tool Call Handler -> Daemon Client (Unix socket)
  |                          \-- Daemon Server (src/daemon/server.ts)
  |                                |-- Connection Pool (src/daemon/pool.ts)
  |                                |     \-- MCP Transport (src/connection/transport.ts)
  |                                |-- Idle Timer (src/daemon/idle.ts)
  |                                \-- Health Endpoint (/health with memory stats)
  |-- Input Validation (src/validation/) -- 48 adversarial patterns
  |-- Schema Introspection (src/schema/)
  |-- Skill Generation (src/generation/)
  \-- Structured Logger (src/logger/) -- JSON on stderr
```

### Key Design Decisions

**Persistent daemon.** MCP servers have a 2-5 second startup cost per connection. The daemon keeps connections alive in a pool, so subsequent calls return in milliseconds instead of seconds. The daemon auto-exits after the idle timeout (default 60s).

**Connection pool with health checks.** Connections are validated before use and recycled on failure. The pool enforces a max size to prevent resource exhaustion.

**Structured JSON everywhere.** stdout is always parseable JSON -- no mixed text output. Logs (when enabled) go to stderr as structured JSON lines. This makes mcp2cli reliable for scripting and piping.

**Semantic exit codes.** Different failure modes get different exit codes so callers can branch on the type of error without parsing output.

**Input validation.** All tool parameters are validated against the MCP schema before the call is dispatched. The validation layer handles 48 adversarial patterns (injection attempts, type coercion, overflow) to fail fast with clear errors.

## Agent Integration

mcp2cli is designed to be called from AI agents via bash tool use. A typical agent workflow:

```bash
# Agent discovers available tools
mcp2cli n8n --help

# Agent reads the schema to understand parameters
mcp2cli schema n8n.n8n_get_workflow

# Agent invokes the tool
mcp2cli n8n n8n_get_workflow --params '{"id": "abc123"}'
```

This pattern keeps MCP tool definitions out of the agent's system prompt entirely. The agent only pays context cost when it actually needs to call a tool, and even then only for the specific tool's schema -- not all tools from all servers.

## Multi-User Authentication

mcp2cli supports multi-user RBAC via `~/.config/mcp2cli/tokens.json`. Each user or agent gets a bearer token with a role.

### tokens.json

```json
{
  "tokens": [
    {
      "id": "rico",
      "token": "your-admin-token-here",
      "role": "admin",
      "description": "Full admin access",
      "username": "rico",
      "password": "your-web-ui-password",
      "expiresAt": "2026-07-01T00:00:00.000Z"
    },
    {
      "id": "skippy",
      "token": "your-agent-token-here",
      "role": "agent",
      "description": "AI agent - tools + read, no config mutations",
      "expiresAt": "2026-07-01T00:00:00.000Z"
    },
    {
      "id": "viewer01",
      "token": "your-viewer-token-here",
      "role": "viewer",
      "description": "Read-only access"
    }
  ]
}
```

Generate secure tokens: `openssl rand -base64 32`

### RBAC Roles

| Permission | viewer | agent | admin |
|------------|--------|-------|-------|
| List services, status | yes | yes | yes |
| Call tools, list tools, schema | no | yes | yes |
| Read credentials | no | yes | yes |
| Add/update/remove services | no | no | yes |
| Write credentials, manage groups | no | no | yes |
| Reload, import, shutdown | no | no | yes |

The `username`/`password` fields enable web UI login at the daemon's root URL. Token-based auth (Bearer header) works for all API and CLI access.

The optional `expiresAt` field enables token expiry and refresh. Expired tokens are rejected. Near-expiry tokens from `tokens.json` can be rotated through `POST /api/auth/refresh`; the daemon writes the new token back to `tokens.json` and hot-reloads token file edits. Local CLI clients proactively refresh near-expiry admin tokens before daemon API calls.

### Fallback Behavior

- **No tokens.json, no env token:** Auth disabled, all requests treated as admin (backward compatible)
- **`MCP2CLI_AUTH_TOKEN` env var only:** Legacy single-token mode, treated as admin
- **tokens.json exists:** Full multi-user RBAC

## Per-Identity Credential Management

Different users and agents can have their own API keys for backend services. When rico calls open-brain, he uses his key. When skippy calls it, the agents' shared key is used.

### credentials.json

Create `~/.config/mcp2cli/credentials.json`:

```json
{
  "groups": {
    "ai_agents": ["skippy", "bilby", "nagatha", "claude"]
  },
  "credentials": {
    "rico": {
      "open-brain": { "headers": { "Authorization": "Bearer ricos-ob-key" } }
    },
    "ai_agents": {
      "open-brain": { "headers": { "Authorization": "Bearer agents-shared-ob-key" } },
      "n8n": { "env": { "N8N_API_KEY": "agents-n8n-key" } }
    }
  },
  "defaults": {
    "proxmox": { "headers": { "Authorization": "PVEAPIToken=shared-token" } }
  }
}
```

### Resolution Chain

When a tool call comes in, credentials are resolved in priority order:

1. **User-specific** -- `credentials[userId][service]`
2. **Group** -- first matching group the user belongs to
3. **Defaults** -- `defaults[service]`
4. **services.json** -- whatever's baked into the service config (backward compatible)

For http/websocket services, credential headers are merged into the connection. For stdio services, credential env vars are merged into the process environment.

For identity-sensitive services, set `requiresCredentials: true` in `services.json`. If no user, group, or explicit default credential exists, the daemon rejects the call instead of using base service headers.

### Credential CLI

```bash
# Set credentials for an identity on a service
mcp2cli credentials set rico open-brain --header "Authorization: Bearer my-key"

# Set env-based credentials (for stdio services)
mcp2cli credentials set rico n8n --env "N8N_API_KEY=my-n8n-key"

# Set a default credential (used when no user/group match)
mcp2cli credentials set-default proxmox --header "Authorization: PVEAPIToken=shared"

# List all credentials (values are redacted)
mcp2cli credentials list

# Show effective credential source for a user
mcp2cli credentials resolve skippy open-brain
# → {"exists": true, "source": "group"}

# Group management
mcp2cli credentials group add ai_agents skippy bilby nagatha
mcp2cli credentials group add-members ai_agents claude
mcp2cli credentials group remove-members ai_agents bilby
mcp2cli credentials group list

# Remove credentials
mcp2cli credentials remove rico open-brain
mcp2cli credentials remove-default proxmox
mcp2cli credentials group remove ai_agents

# Reload from disk after manual edits
mcp2cli credentials reload

# Populate Open Brain credentials from a Vaultwarden item
mcp2cli credentials bootstrap-open-brain --item "Open Brain - Per-User Tokens"
```

### Open Brain Example

Open Brain (OBv2) is an HTTP MCP service where the bearer token controls namespace identity. Do not put an Open Brain `Authorization` header in `services.json`; store it only as a per-identity credential.

**services.json** -- base config for a hosted daemon (no credentials, endpoint only):
```json
{
  "services": {
    "open-brain": {
      "backend": "http",
      "url": "http://open-brain.example.internal:3100/mcp",
      "source": "remote",
      "requiresCredentials": true,
      "preconnect": false
    }
  }
}
```

Use `source: "remote"` when the CLI is routing through a hosted mcp2cli daemon. `requiresCredentials: true` makes missing per-identity credentials fail closed, and `preconnect: false` prevents daemon startup from opening an unauthenticated base Open Brain connection.

**credentials.json** -- per-identity keys:
```json
{
  "groups": {
    "ai_agents": ["skippy", "bilby", "claude"]
  },
  "credentials": {
    "rico": {
      "open-brain": { "headers": { "Authorization": "Bearer ricos-ob-api-key" } }
    },
    "ai_agents": {
      "open-brain": { "headers": { "Authorization": "Bearer agents-shared-ob-key" } }
    }
  }
}
```

Now when rico calls `mcp2cli open-brain search_all --params '{"query": "kubernetes"}'`, his personal key is injected. When skippy calls the same tool, the agents' shared key is used. Each gets their own connection in the pool.

**Vaultwarden bootstrap** -- if the item `Open Brain - Per-User Tokens` has custom fields such as `AUTH_TOKEN_USER_RICO`, `AUTH_TOKEN_USER_SKIPPY`, and `AUTH_TOKEN_USER_BILBY`, run:

```bash
mcp2cli credentials bootstrap-open-brain
```

The field suffix is lowercased and used as the identity (`AUTH_TOKEN_USER_RICO` -> `rico`). Existing credentials are skipped unless `--force` is passed. The command prints counts and identity names only; it does not print bearer tokens.

### Caller Identity Headers

Header and env values support `${caller.id}` and `${caller.role}` template variables. These are replaced with the authenticated caller's identity at call time.

**In services.json** -- inject identity headers for services whose backend trusts caller metadata instead of per-user bearer tokens:
```json
{
  "services": {
    "example-service": {
      "backend": "http",
      "url": "https://example.internal/mcp",
      "headers": {
        "X-Agent-Id": "${caller.id}",
        "X-Role": "

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [rodaddy](https://github.com/rodaddy)
- **Source:** [rodaddy/mcp2cli](https://github.com/rodaddy/mcp2cli)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-rodaddy-mcp2cli
- Seller: https://agentstack.voostack.com/s/rodaddy
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.