@blac3k/bash-mcp v1.0.0

Bash MCP Server (bash-mcp)

A Model Context Protocol (MCP) server that allows compatible clients (like Large Language Models) to execute arbitrary bash commands on the host machine.

🚨 EXTREME CAUTION: SECURITY WARNING 🚨

This server provides a tool (execute-bash-command) that runs ANY command string it receives directly in a bash shell on the machine where it is running.

• Command Injection Vulnerability: There is NO sanitization or validation beyond basic structure. Malicious commands (e.g., rm -rf /, wget ... | bash) WILL BE EXECUTED if sent by the client.
• Intended Use: This tool is designed ONLY for trusted local execution where you have full control over the MCP client sending the commands.
• DO NOT expose this server to untrusted networks or users.
• DO NOT run this server with elevated privileges (root/sudo) unless absolutely necessary and you fully understand the immense risks.

You are solely responsible for any consequences resulting from the execution of commands via this server.

Features

• Provides a standard MCP interface over stdio.
• Exposes a single tool: execute-bash-command.

Installation & Usage

The intended way to use this server is via npx, which will download and run it temporarily.

npx -y @blac3k/bash-mcp

This command starts the server, listening for an MCP client connection on standard input/output. The server will print diagnostic messages to standard error.

MCP Tool: execute-bash-command

• Name: execute-bash-command
• Description: Executes a given command string in the /usr/bin/bash shell and returns its output.
• Input Schema:
  • command (string, required): The bash command to execute.
• Output: A text block containing:
  • A success or failure message.
  • Standard Output (stdout) of the command (if any), labelled --- STDOUT ---.
  • Standard Error (stderr) of the command (if any), labelled --- STDERR ---. Note that stderr might be included even if the command exits successfully, as some tools use it for non-error messages.
  • An error message if the execution itself failed (e.g., command not found), labelled --- ERROR ---.

Development

1. Clone the repository:

   git clone https://github.com/albiol2004/bash-mcp.git
   cd bash-mcp

2. Install dependencies:

   npm install

3. Build the project: (Compiles TypeScript to JavaScript in build/)

   npm run build

4. Link for local execution: (Makes the bash-mcp command available globally, pointing to your local build)

   npm link

5. Run the linked server:

   bash-mcp # Or use 'npm run dev' which builds and runs

   Make changes in the src/ directory, then run npm run build again to see them reflected when you run bash-mcp.

License

This project is licensed under the ISC License.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.