# cmd-line-mcp

[![npm version](https://badge.fury.io/js/cmd-line-mcp.svg)](https://www.npmjs.com/package/cmd-line-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)

A secure Model Context Protocol (MCP) server that allows AI assistants to execute terminal commands with controlled directory access and command permissions.

Written in **JavaScript (ESM)** — works with `npx` out of the box, no Python runtime required.

---

## Quick Start

### Run with npx (no install)

```bash
npx cmd-line-mcp
npx cmd-line-mcp --config /path/to/config.json
npx cmd-line-mcp --config config.json --env .env
```

### Global install

```bash
npm install -g cmd-line-mcp
cmd-line-mcp
```

### Local install

```bash
npm install cmd-line-mcp
npx cmd-line-mcp
```

---

## Claude Desktop Integration

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "cmd-line": {
      "command": "npx",
      "args": ["-y", "cmd-line-mcp"],
      "env": {
        "CMD_LINE_MCP_SECURITY_REQUIRE_SESSION_ID": "false",
        "CMD_LINE_MCP_SECURITY_AUTO_APPROVE_DIRECTORIES_IN_DESKTOP_MODE": "true"
      }
    }
  }
}
```

Or with a custom config file:

```json
{
  "mcpServers": {
    "cmd-line": {
      "command": "npx",
      "args": ["-y", "cmd-line-mcp", "--config", "/path/to/config.json"]
    }
  }
}
```

Restart Claude for Desktop after saving.

---

## Configuration

Configuration is resolved in this order (later overrides earlier):

1. Built-in `default_config.json`
2. File pointed to by `CMD_LINE_MCP_CONFIG` environment variable
3. `--config <path>` CLI argument
4. `.env` file (searched from cwd upward)
5. `CMD_LINE_MCP_*` environment variables

### Example `config.json`

```json
{
  "security": {
    "whitelisted_directories": ["/home", "/tmp", "~/Projects"],
    "auto_approve_directories_in_desktop_mode": false,
    "require_session_id": false,
    "allow_command_separators": true
  },
  "commands": {
    "read": ["ls", "cat", "grep"],
    "write": ["touch", "mkdir", "rm"],
    "system": ["ps", "ping"]
  }
}
```

### Environment Variable Format

```
CMD_LINE_MCP_<SECTION>_<SETTING>
```

Examples:

```bash
export CMD_LINE_MCP_SECURITY_WHITELISTED_DIRECTORIES="/projects,/var/data"
export CMD_LINE_MCP_SECURITY_AUTO_APPROVE_DIRECTORIES_IN_DESKTOP_MODE=true
export CMD_LINE_MCP_COMMANDS_READ="awk,jq,wc"
```

---

## Available MCP Tools

| Tool | Description |
|------|-------------|
| `execute_command` | Execute any allowed command (read/write/system) |
| `execute_read_command` | Execute read-only commands only |
| `approve_directory` | Grant access to a directory for a session |
| `approve_command_type` | Grant permission for a command category |
| `list_directories` | List whitelisted and approved directories |
| `list_available_commands` | Show commands grouped by category |
| `get_command_help` | Get usage guidance and examples |
| `get_configuration` | View current server configuration |

---

## Supported Commands (default)

### Read (no approval needed)
`ls`, `pwd`, `cat`, `less`, `head`, `tail`, `grep`, `find`, `which`, `du`, `df`, `file`, `uname`, `hostname`, `uptime`, `date`, `whoami`, `id`, `env`, `history`, `sort`, `wc`, ...

### Write (approval required)
`cp`, `mv`, `rm`, `mkdir`, `rmdir`, `touch`, `chmod`, `chown`, `ln`, `echo`, `tar`, `gzip`, `zip`, `unzip`, `awk`, `sed`, ...

### System (approval required)
`ps`, `top`, `htop`, `who`, `netstat`, `ifconfig`, `ping`, `ssh`, `curl`, `wget`, `xargs`, ...

### Blocked (always denied)
`sudo`, `su`, `bash`, `sh`, `zsh`, `eval`, `exec`, `dd`, `mkfs`, `shutdown`, `reboot`, ...

---

## Security Architecture

```
┌───────────────────────────────────────────────────────────────┐
│                   COMMAND-LINE MCP SERVER                     │
├──────────────────┬────────────────────────┬───────────────────┤
│ COMMAND SECURITY │   DIRECTORY SECURITY   │ SESSION SECURITY  │
├──────────────────┼────────────────────────┼───────────────────┤
│ ✓ Read commands  │ ✓ Directory whitelist  │ ✓ Session IDs     │
│ ✓ Write commands │ ✓ Runtime approvals    │ ✓ Persistent      │
│ ✓ System commands│ ✓ Path validation      │   permissions     │
│ ✓ Blocked list   │ ✓ Home dir expansion   │ ✓ Auto timeouts   │
│ ✓ Pattern filters│ ✓ Subdirectory check   │ ✓ Desktop mode    │
└──────────────────┴────────────────────────┴───────────────────┘
```

---

## Requirements

- Node.js >= 18
- macOS or Linux

---

## License

MIT

---

## Original Python source

The original Python implementation is preserved in the [`temp/`](./temp) directory for reference.