home / mcp / shell executor mcp server
local mcp server
Configuration
View docs{
"mcpServers": {
"kosiew-zmcp": {
"command": "python",
"args": [
"src/mcp_server.py"
],
"env": {
"MCP_API_TOKEN": "your-secret-token"
}
}
}
}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.
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.
# 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-mcpTo 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.
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.
- 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.
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.
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.
List directory contents in long or short form depending on flags.
Display file contents, supporting multiple files and piping.
Show the first lines of a file, with optional line count.
Show the last lines of a file, with optional line count.
Search for files and directories matching given patterns.
Display a tree-like directory structure.
Count lines, words, and bytes in text.
Estimate file and directory space usage.
Display filesystem disk space usage.
Determine file type and metadata.
Display file or filesystem status information.
Print the current working directory.
Search text using patterns across files or input streams.
Stream editor for filtering and transforming text.
Pattern scanning and processing language for text data.
Sort lines of text based on keys.
Report or filter duplicate lines in text.
Remove sections from each line of files.
Translate or delete characters.
Version control commands for repositories.
Node package manager commands for package management.
Alternative package manager for Node.js projects.
Python package manager commands.
Execute Python scripts or modules.
Run Node.js programs.
Rust package manager and build tool.
Utility to build and manage projects.
Rust compiler for compiling Rust source code.
Go language tooling and builds.
Java runtime and tool execution.
Java compiler for Java source files.
Report currently running processes.
Show how long the system has been running.
Print the current user identity.
Display user identity and group memberships.
Print system information.
Locate a command in PATH.
Transfer data from or to a server using various protocols.
Retrieve files from the web.
Send ICMP echo requests to test reachability.
Query DNS information.
Query DNS information in a simplified form.
Archive files using the tar format.
Package files into a ZIP archive.
Extract files from a ZIP archive.
Compress or decompress files using gzip.
Decompress gzip-compressed files.
Output specified text to standard output.
Display current date and time.
Display a calendar.
Arbitrary-precision calculator language.
Evaluate expressions as part of shell scripting.
Strip directory and suffix from file names.
Strip last component from a file path.
Compute MD5 hash of input.
Compute SHA-256 hash of input.
Compute SHA checksums.