Command Executor

🚀 MCP Command Executor

The MCP Command Executor is a server implemented based on the MCP protocol, allowing for the secure execution of system commands. The server ensures security by only executing commands registered in the allowlist.

🚀 Quick Start

Prerequisites

• Go 1.24 or higher
• github.com/metoro-io/mcp-golang
• Other dependencies are listed in go.mod

Installation

You can install the MCP Command Executor using the following methods:

go install github.com/cnosuke/mcp-command-exec

Or clone the repository and build it manually:

git clone https://github.com/cnosuke/mcp-command-exec.git
cd mcp-command-exec
make build

Configuration

The server is configured through a YAML file (default: config.yml). Here is an example:

# Log configuration
log: 'log/mcp-command-exec.log'
debug: false

command_exec:
  allowed_commands:
    - git
    - ls
    - mkdir
    - cd
    - npm
    - npx
    - python
  # Working directory settings
  default_working_dir: '/home/user'
  allowed_dirs:
    - '/home/user/projects'
    - '/tmp'
  # Path search settings
  search_paths:
    - '/usr/local/bin'
    - '/usr/bin'
  path_behavior: 'prepend' # prepend, replace, append
  # Global environment variables
  environment:
    HOME: '/home/user'
    GOPATH: '/home/user/go'
    GOMODCACHE: '/home/user/go/pkg/mod'
    LANG: 'en_US.UTF-8'

You can override the configuration via environment variables:

• LOG_PATH: Specify the log file path
• DEBUG: Enable debug mode (true/false)
• ALLOWED_COMMANDS: A comma-separated list of allowed commands (overrides the configuration file)

Example:

ALLOWED_COMMANDS=git,ls,cat,echo mcp-command-exec server

Logging

The logging behavior is controlled by the configuration:

• If log is set in the configuration file, logs will be written to the specified file.
• If log is empty, no logs will be generated.
• Set debug: true to enable more detailed logging.

Command-line Arguments

When starting the server, you can specify various settings:

./bin/mcp-command-exec server [options]

Options:

• --config, -c: Specify the configuration file path (default: "config.yml").

✨ Features

• Execute commands via the MCP protocol.
• Filter commands using an allowlist.
• Customize allowed commands through environment variables:
  • Global environment variables in the configuration file.
  • Specific environment variables for each command.
• Return command execution results as text output.

💻 Usage Examples

Basic Usage

To start the server with custom allowed commands:

ALLOWED_COMMANDS=git,ls,cat,echo mcp-command-exec server

📚 Documentation

MCP Tool Specification

Configuration File Structure

{
  "command_exec": {
    "allowed_commands": [
      "git",
      "ls",
      "mkdir",
      "cd",
      "npm",
      "npx",
      "python"
    ],
    "default_working_dir": "/home/user",
    "allowed_dirs": [
      "/home/user/projects",
      "/tmp"
    ],
    "search_paths": [
      "/usr/local/bin",
      "/usr/bin"
    ],
    "path_behavior": "prepend",
    "environment": {
      "HOME": "/home/user",
      "GOPATH": "/home/user/go",
      "GOMODCACHE": "/home/user/go/pkg/mod",
      "LANG": "en_US.UTF-8"
    }
  }
}

Environment Variables

Set global environment variables through the environment field in the configuration file.

Allowed Command List

Specify the allowed commands in allowed_commands. For example:

"allowed_commands": [
  "git",
  "ls",
  "mkdir",
  "cd",
  "npm",
  "npx",
  "python"
]

Working Directory Settings

The default working directory is specified by default_working_dir, and the list of allowed directories is specified in allowed_dirs.

Path Search Behavior

Control the behavior of command path search through the path_behavior field. Available values include:

• prepend: Prepend the custom path to the system PATH.
• replace: Replace the system PATH entirely with the custom path.
• append: Append the custom path to the end of the system PATH.

Security Measures

1. Command Filtering: Only specified commands are allowed to pass.
2. Directory Restriction: All commands must be executed within the allowed directories.
3. Environment Isolation: Each command runs in a sandbox environment to prevent interference with each other.

Development Information

Project Structure

mcp-command-exec/
├── main.go           # Main program entry
├── config.yml       # Configuration file
└── Makefile         # Build script

Compilation and Execution

make build     # Compile the executable file
make run      # Run the server
make install  # Install to the system

📄 License

This project is licensed under the MIT License.

Author: cnosuke ( x.com/cnosuke )