Shell Executor

You can run safe shell commands through an MCP server that validates commands against a whitelist and exposes a simple, standardized interface. This enables AI agents and tools to perform file operations, text processing, development tasks, and system queries in a controlled, auditable way. The server communicates over JSON-RPC via stdio, making it easy to integrate with editors like VS Code Copilot or other MCP clients.

How to use

Connect your MCP client to the Shell Executor MCP Server using the standard stdio interface. You will typically start the server locally and point your client at its stdin/stdout channels or configure a client to launch the server process as a subprocess. Once connected, you can request tool capabilities, initialize the session, and issue commands to be executed in a safe, whitelist-filtered environment.

How to install

# Prerequisites
# - Python 3.8+ installed
# - git available

# Option A: Clone and install in editable mode
git clone https://github.com/yourusername/shell-executor-mcp.git
cd shell-executor-mcp
pip install -e .

# Option B: Install from PyPI (when published)
pip install shell-executor-mcp

Notes on setup and usage

To run the server locally, start the Python module that serves the MCP protocol. Then connect your MCP client to the running process to issue commands like listing directories, viewing file contents, or initiating toolchains. Security is enforced through a whitelist of allowed commands, a maximum execution timeout, and controlled environment variables.

Additional configuration and examples

Configure your MCP client to pass an API token if required by your setup. For example, you can supply an environment variable in the client process or within your editor integration to authenticate with the shell executor. Common environment controls include restricting variables that influence command execution.

Security and behavior notes

• Commands are filtered through a whitelist to prevent unsafe operations.
• A 30-second execution timeout is enforced to avoid long-running tasks.
• Destructive operations (such as removing or overwriting critical files) are not allowed.
• Privilege escalation (sudo, su) is disallowed.
• You can control environment variables exposed to executed commands.

Troubleshooting

If your client cannot connect, verify that the server process is running and that the stdio channel is correctly wired. Check that the authentication token (if used) is set in the client configuration. Review any whitelist settings to ensure your intended commands are permitted.

Notes

The server supports a broad set of common shell operations and development tools. Typical workflows include file system navigation, text processing, version control operations, language toolchains, and system information queries. Always prefer running commands that are explicitly allowed by the whitelist and monitor the outputs for auditing and safety.

Available tools

ls

List directory contents in long or short form depending on flags.

cat

Display file contents, supporting multiple files and piping.

head

Show the first lines of a file, with optional line count.

tail

Show the last lines of a file, with optional line count.

find

Search for files and directories matching given patterns.

tree

Display a tree-like directory structure.

wc

Count lines, words, and bytes in text.

du

Estimate file and directory space usage.

df

Display filesystem disk space usage.

file

Determine file type and metadata.

stat

Display file or filesystem status information.

pwd

Print the current working directory.

grep

Search text using patterns across files or input streams.

sed

Stream editor for filtering and transforming text.

awk

Pattern scanning and processing language for text data.

sort

Sort lines of text based on keys.

uniq

Report or filter duplicate lines in text.

cut

Remove sections from each line of files.

tr

Translate or delete characters.

git

Version control commands for repositories.

npm

Node package manager commands for package management.

yarn

Alternative package manager for Node.js projects.

pip

Python package manager commands.

python

Execute Python scripts or modules.

node

Run Node.js programs.

cargo

Rust package manager and build tool.

make

Utility to build and manage projects.

rustc

Rust compiler for compiling Rust source code.

go

Go language tooling and builds.

java

Java runtime and tool execution.

javac

Java compiler for Java source files.

ps

Report currently running processes.

uptime

Show how long the system has been running.

whoami

Print the current user identity.

id

Display user identity and group memberships.

uname

Print system information.

which

Locate a command in PATH.

curl

Transfer data from or to a server using various protocols.

wget

Retrieve files from the web.

ping

Send ICMP echo requests to test reachability.

dig

Query DNS information.

nslookup

Query DNS information in a simplified form.

tar

Archive files using the tar format.

zip

Package files into a ZIP archive.

unzip

Extract files from a ZIP archive.

gzip

Compress or decompress files using gzip.

gunzip

Decompress gzip-compressed files.

echo

Output specified text to standard output.

date

Display current date and time.

cal

Display a calendar.

bc

Arbitrary-precision calculator language.

expr

Evaluate expressions as part of shell scripting.

basename

Strip directory and suffix from file names.

dirname

Strip last component from a file path.

md5

Compute MD5 hash of input.

sha256sum

Compute SHA-256 hash of input.

shasum

Compute SHA checksums.