home / mcp / command-line mcp server

Command-Line MCP Server

Provides a secure MCP server to run terminal commands with directory access controls and per-command permissions.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "andresthor-cmd-line-mcp": {
      "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"
      }
    }
  }
}

You run a secure MCP server that lets AI assistants execute terminal commands with strict controls over which directories can be accessed and which commands are allowed. This setup helps you safely delegate automation while protecting sensitive data and system integrity.

How to use

You interact with the MCP server through an MCP client. Start by starting the local MCP server process, then connect your client to the server using the configured command and environment. The server enforces per-command permissions and directory whitelisting, so read-only tasks (like listing files) require no write privileges, while actions that modify data or affect the system require explicit approvals. When a command is requested, the server checks the command category and the target directory, and it applies session-based approvals where needed. You can request directory access, list currently allowed directories, and run eligible commands within the defined security policy.

How to install

Prerequisites: you need Python installed and access to a shell. You will set up a virtual environment, install the MCP server package in editable mode, and prepare a configuration file.

# Clone the project
git clone https://github.com/andresthor/cmd-line-mcp.git
cd cmd-line-mcp

# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate

# Install the MCP server in editable mode
pip install -e .

# Copy a sample configuration to start with
cp config.json.example config.json

# Run the server with the default config
cmd-line-mcp

# Or run with a specific config
cmd-line-mcp --config config.json
"}]},{

Configuration and security notes

Security is built around two pillars: which commands are allowed and which directories can be accessed. You can customize the lists of read, write, system, and blocked commands, as well as the set of whitelisted directories. You can also control whether directories are auto-approved in desktop mode and whether session IDs are required.

Key configuration options include: a list of whitelisted directories, category-based command permissions, and the setting that controls whether command separators (like pipes and sequences) are allowed in a single command chain. You can adapt these settings to be highly restrictive or more permissive depending on your threat model and workflow.

Environment variables can override settings and extend command lists. You can add read commands, adjust desktop-mode behavior, and merge new command entries with existing defaults.

Claude Desktop integration tips

If you use Claude Desktop, you can configure a local MCP server entry that points to your Python virtual environment and the server config. The setup includes a command path to the MCP executable and arguments specifying the config file. This keeps your session aligned with directory approvals and command permissions.

Example configuration for Claude Desktop shows a server entry with the command path and arguments, plus environment variables that adjust security behavior for desktop mode.

Troubleshooting and tips

If you encounter permission errors, verify that the requested directory is whitelisted for the current session and that the command belongs to an allowed category. Check session IDs and ensure you have the necessary approvals for write or system commands. If approvals are stuck in a loop, review the desktop mode settings to avoid repeated prompts.

Available tools

execute_command

Run any command type through the MCP server, subject to permission checks and directory restrictions.

execute_read_command

Run read-only commands with directory approval as needed.

approve_directory

Grant access to a directory for the current session.

approve_command_type

Grant permission for a specific category of commands (read/write/system).

list_directories

Show the directories currently whitelisted for the server.

list_available_commands

Show the available command categories and their members.

get_command_help

Get usage guidance for supported commands.

get_configuration

View current security and command configuration.