Command Line MCP server

This command-line MCP server provides a secure layer between AI assistants and your terminal, implementing a dual security model that controls both command permissions and directory access. It allows AI assistants to safely execute terminal commands within your specified security boundaries.

Installation

Basic Installation

# Install
git clone https://github.com/yourusername/cmd-line-mcp.git
cd cmd-line-mcp
python -m venv venv
source venv/bin/activate
pip install -e .
cp config.json.example config.json

# Run
cmd-line-mcp                        # With default config
cmd-line-mcp --config config.json   # With specific config

Alternatively, you can install directly from PyPI:

pip install cmd-line-mcp

Configuration Setup

The server supports four configuration methods in order of precedence:

1. Built-in default configuration
2. JSON configuration file (recommended for customization)

   cmd-line-mcp --config config.json
   

3. Environment variables

   export CMD_LINE_MCP_SECURITY_WHITELISTED_DIRECTORIES="~,/tmp"
   

4. .env file

   cmd-line-mcp --config config.json --env .env
   

Core Configuration Settings

Create a config.json file with settings like:

{
  "security": {
    "whitelisted_directories": ["/home", "/tmp", "~"],
    "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

Environment variables follow this naming pattern:

CMD_LINE_MCP_<SECTION>_<SETTING>

Examples:

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"

Claude Desktop Integration

Setup

1. Install Claude for Desktop
2. Configure in ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cmd-line": {
      "command": "/path/to/venv/bin/cmd-line-mcp",
      "args": ["--config", "/path/to/config.json"],
      "env": {
        "CMD_LINE_MCP_SECURITY_REQUIRE_SESSION_ID": "false",
        "CMD_LINE_MCP_SECURITY_AUTO_APPROVE_DIRECTORIES_IN_DESKTOP_MODE": "true"
      }
    }
  }
}

Recommended Settings

For best experience with Claude Desktop:

• Set require_session_id: false (essential to prevent approval loops)
• Set auto_approve_directories_in_desktop_mode: true (optional for convenience)
• Include common directories in your whitelist

After configuration, restart Claude for Desktop.

Using MCP Tools

The server provides these MCP tools for AI assistants:

Directory Management

# Check available directories
dirs = await list_directories(session_id="session123")
whitelisted = dirs["whitelisted_directories"]
approved = dirs["session_approved_directories"]

# Request permission for a directory
if "/projects/my-data" not in whitelisted and "/projects/my-data" not in approved:
    result = await approve_directory(
        directory="/projects/my-data", 
        session_id="session123"
    )

Command Execution

# Read commands (read permissions enforced)
result = await execute_read_command("ls -la ~/Documents")

# Any command type (may require command type approval)
result = await execute_command(
    command="mkdir -p ~/Projects/new-folder", 
    session_id="session123"
)

Configuration Information

# Check current settings
config = await get_configuration()
whitelist = config["directory_whitelisting"]["whitelisted_directories"]

Security System

Directory Security Modes

The system supports three security modes:

• Strict: Only whitelisted directories allowed
• Approval: Non-whitelisted directories require explicit approval
• Auto-approve: Auto-approves directories for Claude Desktop

Directory Approval Flow

1. Command is requested in a directory
2. System checks:
   • Is the directory in the global whitelist? → Allow
   • Has directory been approved in this session? → Allow
   • Neither? → Request approval
3. After approval, directory remains approved for the entire session

Command Categories

Commands are categorized for security control:

• Read: Safe operations (ls, cat, find) - No approval required
• Write: Data modification (mkdir, rm, touch) - Requires approval
• System: System operations (ps, ping, ifconfig) - Requires approval
• Blocked: Dangerous commands (sudo, bash, eval) - Always denied

Command Chaining

The server supports command chaining methods:

• Pipes: ls | grep txt
• Sequence: mkdir dir; cd dir
• Background: find . -name "*.log" &

Enable/disable with the allow_command_separators setting.

Customizing Commands

Add custom commands to your configuration:

{
  "commands": {
    "read": ["ls", "cat", "grep", "awk", "jq"],
    "write": ["mkdir", "touch", "rm"],
    "system": ["ping", "ifconfig", "kubectl"],
    "blocked": ["sudo", "bash", "eval"]
  }
}

Or use environment variables to add commands:

export CMD_LINE_MCP_COMMANDS_READ="awk,jq"
export CMD_LINE_MCP_COMMANDS_BLOCKED="npm,pip"

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "cmd-line" '{"command":"cmd-line-mcp","args":[]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cmd-line": {
            "command": "cmd-line-mcp",
            "args": []
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "cmd-line": {
            "command": "cmd-line-mcp",
            "args": []
        }
    }
}

3. Restart Claude Desktop for the changes to take effect