mcp-servers/mcp-bash-server/README.md
A HertzBeat MCP server for running scripts with security command blacklist and logging capabilities
If you need to deploy this MCP Server locally, you will need a Rust runtime environment.
Visit rust-lang.org to learn how to install the Rust runtime environment.
Version 1.88.0 can absolutely work, and we recommend using the latest version of Rust.
If you want to run this MCP server locally using the default settings provided by the project, simply run the following command in the project root directory:
cargo run
This MCP server will be deployed at http://127.0.0.1:4000/mcp, and you can use the modelcontextprotocol/inspector tool to connect to and use this MCP server.
For information on how to use the modelcontextprotocol/inspector tool, refer to the inspector documentation.
If you encounter any issues while using Inspector, it is recommended to use version v0.16.2. Other versions may also work.
Using container deployment for this MCP Server is an excellent way to try out the tools provided by the server without polluting your machine, as all MCP Server operations are completed within the container.
Refer to the Dockerfile in the code repository and create your own Dockerfile. After creating it, run the following build command:
docker build -t apache/hertzbeat-mcp-bash-server:latest .
You can use the proxy in docker build
docker build --build-arg HTTPS_PROXY=<your https_proxy> --build-arg HTTP_PROXY=<your http_proxy> -t apache/hertzbeat-mcp-bash-server:latest .
After building, use the following command to run it:
docker run -d --name mcp-bash-server -p 4000:4000 --restart unless-stopped apache/hertzbeat-mcp-bash-server:latest
The MCP Server inside the container runs on 0.0.0.0:4000. On the host machine, use the inspector with URL http://localhost:4000/mcp to connect to the MCP Server inside the container.
Container's workdir is /app and it will run the /app/mcp-bash-server when it start, this program will read the config.toml at the same directory, so you can put the config.toml in the /app directory to cover the default config in image. Use the command below to do it.
docker run -d --name mcp-bash-server -p 4000:4000 -v `pwd`/config.toml:/app/config.toml --restart unless-stopped apache/hertzbeat-mcp-bash-server:latest
If you are using SELinux, you may need to run the command instead to let the container access the file in host.
docker run -d --name mcp-bash-server -p 4000:4000 -v `pwd`/config.toml:/app/config.toml:Z --restart unless-stopped apache/hertzbeat-mcp-bash-server:latest
To check if the config.toml is used, do this
docker logs mcp-bash-server
or check the config.toml in container
docker exec mcp-bash-server ls /app
docker exec mcp-bash-server cat /app/config.toml
Start the MCP Server in daemon mode, then add the settings to your Vscode Copilot mcp config. Note that you can use modelcontextprotocol/inspector to finish the OAuth flow and get the access token, put it in config and restart server, then Copilot can connect to the server and use the tools.
{
"servers": {
"bash-server": {
"url": "http://localhost:4000/mcp",
"headers": {
"Authorization": "Bearer <your-token>"
}
}
}
}
Currently Vscode MCP OAuth can not automatically authorize this bash-server The vscode mcp OAuth flow is:
But we requires the client registration before accessing endpoint /authorize with query-params that contains invalid client-id. So we can only set the token manually now.
The config.toml file contains the settings for this MCP server. The configuration items currently supported by the configuration file are as follows:
# This is the configuration file for mcp-bash-server
[settings]
# Port for MCP Server deployment
port = 4000
# IP for MCP Server deployment
host = "127.0.0.1"
# Usage environment for MCP Server, can be either development or production environment.
# Set env to "development" or "production"; production uses OAuth 2.0.
env = "development"
[whitelist]
# Whitelist of allowed commands (exact match), a string list.
# Only commands where the complete command string exactly matches an item in this list will be allowed
commands = [
"echo hello",
"ls -la",
"pwd",
# Add your allowed commands here
]
# Whitelist of allowed command regex patterns, a list of regex expression strings
# Commands where the complete command string matches any of these regex patterns will be allowed
regex = [
'^echo [a-zA-Z0-9 ]+$',
'^ls [a-zA-Z0-9 /-]*$',
# Add your whitelist regex patterns here
]
[blacklist]
# Blacklist of forbidden commands (exact match), a string list
# Blacklist has higher priority than whitelist. If the complete command string exactly matches an item in this list, the entire command will be blocked, even if it would be allowed by the whitelist
# Note: Only exact matches are blocked. For example, if "rm" is blacklisted, only the exact command "rm" is blocked, not commands like "rm -rf /tmp/test"
commands = [
# Dangerous file operations
"rm -rf /",
"shutdown",
# Add your forbidden commands here
]
# Blacklist of forbidden command regex patterns, a list of regex expression strings
# Blacklist has higher priority than whitelist. If the complete command string matches any of these regex patterns, it will be blocked, even if it would be allowed by the whitelist
regex = [
# Block any command with dangerous operators
'.*[|&;`$()><].*',
# Block commands that try to write to system directories
'.*/etc/.*',
'.*/root/.*',
# Block commands with sudo or su
'^sudo .*',
'^su .*',
# Add your blacklist regex patterns here
]
Run cargo test to execute all unit tests.
The unit tests include:
config.rs)validator.rs)bash_server.rs)execute_script and execute_pythonUse the official MCP debugging tool modelcontextprotocol/inspector. For usage instructions, refer to the inspector documentation.
If you deploy the MCP Server locally using the default method, run the inspector debugging tool after the server starts.
npx @modelcontextprotocol/inspector
Then set the connection method to Streamable HTTP and set the URL to http://127.0.0.1:4000/mcp.
If your running mode is development, you don't need to go through Open Auth Settings and can directly click Connect to connect to the MCP Server. If your running mode is production, you need to complete the Open Auth Settings verification.
The method for using OAuth verification and connection is as follows:
Open Auth SettingsQuick OAuth FlowApprove on the pop-up webpageAuthentication Complete in OAuth Flow Progress. Copy the access_token from thereAuthentication, paste the previously copied token into the Bearer Token field, then click ConnectAfter connecting, you can test the various tools provided by the MCP Server in the inspector.
The MCP Server currently provides the following tools:
all_execute_via_default_shell
command: The bash command or script to executeworking_dir: Working directory for the command (optional)env_vars: Environment variables (optional)timeout_seconds: Timeout in seconds (default: 30)execute_python
execute_script
unix_get_system_info_via_default_shell
unix_preset_get_system_info_via_default_shell
unix_get_available_shell
unix_preset_get_nic_info_via_default_shell
unix_preset_get_cpu_info_via_default_shell
unix_preset_get_disk_free_info_via_default_shell
unix_preset_get_top10_cpu_processes_via_default_shell
unix_preset_get_top10_mem_processes_via_default_shell
All command execution tools support comprehensive security validation:
"rm" is blacklisted, only the exact command "rm" is blocked, not commands like "rm -rf /tmp/test" (which would be evaluated separately against the whitelist)bash -c "command")