bash-mcp
It's a (now deprecated) MCP server that lets an agent run arbitrary shell commands on the host, including long-running background processes.
run— execute any shell command and get back stdout, stderr, and the command itself as JSON; optionally set acwdand atimeout(default 30s).run_background— launch a long-running process (e.g. a dev server) under a uniquename, with optionalcwd; returns the PID.kill_background— stop a named background process.list_background— list all currently running background processes.Output overflow handling — oversized output is truncated at
BASH_MCP_MAX_OUTPUT_SIZE(default 50KB) with the full output written to a private temp file whose path is returned; temp dir configurable viaBASH_MCP_TEMP_DIR.Automatic cleanup — background processes are terminated when the server shuts down.
Note: unmaintained since Oct 29, 2026; prefer your agent's built-in shell tools or Desktop Commander.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@bash-mcp start a background process for npm run dev"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
DEPRECATED_bash-mcp
This project is no longer maintained. Development and support ended on October 29, 2026. No new features, bug fixes, dependency updates, or security patches will be provided. Do not use this project for new integrations.
Use your coding agent's built-in shell tools when available. Claude Code supports shell commands, background tasks, and output retrieval. For MCP clients that need a separate terminal server, evaluate Desktop Commander. Its configuration and tool names differ from bash-mcp.
Historical documentation
The documentation below is retained for historical reference.
A simple MCP (Model Context Protocol) server that enables Claude to execute shell commands without permission prompts.
⚠️ Security Warning: This server executes arbitrary shell commands. Use with caution and only in trusted environments.
Related MCP server: Shell Exec MCP
Installation
# Install globally
npm install -g bash-mcp
# Or use with npx
npx bash-mcpQuick Start
For Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"bash": {
"command": "npx",
"args": ["bash-mcp"]
}
}
}For Claude Code (Cursor, VS Code)
Open command palette (Cmd/Ctrl + Shift + P)
Run "MCP: Add Server"
Select "NPM" as the server type
Enter:
bash-mcp
Available Tools
run - Execute a command
// Simple command
run("ls -la")
// With working directory
run("npm test", { cwd: "/path/to/project" })
// With timeout (milliseconds)
run("long-running-command", { timeout: 60000 })run_background - Start a background process
// Start a dev server
run_background("npm run dev", "frontend")
// Start backend service with working directory
run_background("./gradlew bootRun", "backend", { cwd: "./backend" })kill_background - Stop a background process
kill_background("frontend")list_background - List all background processes
list_background()Example Usage
User: Start the development servers
Assistant: I'll start both frontend and backend servers for you.
[Uses run_background tool]
Started frontend server (PID: 12345)
Started backend server (PID: 12346)
User: Check if they're running
Assistant: [Uses list_background tool]
Both servers are running successfully!Response Format
All tools return JSON formatted responses:
{
"success": true,
"stdout": "command output",
"stderr": "error output if any",
"command": "executed command"
}For background processes:
{
"success": true,
"name": "frontend",
"pid": 12345,
"command": "npm run dev",
"message": "Started background process 'frontend' (PID: 12345)"
}Features
Execute any shell command without permission prompts
Run long-running processes in the background
Manage background processes (list, kill)
Capture stdout and stderr
Set working directory for commands
Configure timeout for commands
Automatic cleanup on server shutdown
NEW: Automatic output truncation with full output saved to temp files
NEW: Configurable output size limits and temp directory via environment variables
Environment Variables
BASH_MCP_MAX_OUTPUT_SIZE: Maximum output size in bytes before truncation (default: 51200/50KB)BASH_MCP_TEMP_DIR: Directory for storing full output when truncated (default: system temp directory)
Example Configuration
{
"mcpServers": {
"bash": {
"command": "npx",
"args": ["bash-mcp"],
"env": {
"BASH_MCP_MAX_OUTPUT_SIZE": "102400",
"BASH_MCP_TEMP_DIR": "/tmp/bash-mcp-outputs"
}
}
}
}Output Overflow Handling
When command output exceeds BASH_MCP_MAX_OUTPUT_SIZE:
Output is truncated to the specified limit
Full output is saved to a temporary file
The response includes the file path where full output can be found
If custom temp directory fails, falls back to system temp directory
Security Considerations
This MCP server executes arbitrary shell commands with the same privileges as the Node.js process. Only use in development environments or trusted contexts.
Requirements
Node.js >= 20.0.0
npm or npx
License
MIT
Author
tinywind tinywind0@gmail.com
Contributing
This project no longer accepts feature requests, bug reports, or pull requests. Fork the repository if you need to maintain a version.
Temporary output security
Overflow output is written to a private directory under BASH_MCP_TEMP_DIR, with an operating-system temporary directory fallback. On POSIX systems, directories use mode 0700 and files use mode 0600. Files are created exclusively, and background process names are not used as path components. Full output files remain available at the paths returned by the tools.
npm test exercises the public MCP executable and verifies that pre-created symlinks cannot overwrite existing files for normal output, fallback output, or background stdout/stderr.
Available Tools
4 toolskill_backgroundA
Kill a background process by name
Inputs: name (required).
list_backgroundA
List all running background processes
Inputs: no named parameters.
runC
Execute a shell command and return output
Inputs: command (required), cwd, timeout.
run_backgroundB
Run a command in background
Inputs: name (required), command (required), cwd.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a distinct purpose: run executes synchronously, run_background launches asynchronously, list_background inspects, and kill_background terminates. No overlapping actions or ambiguous boundaries.
All tools follow a clear verb-based pattern: run, run_background, kill_background, list_background. The _background suffix consistently identifies async operations while the base verbs are predictable.
Four tools provide a focused, minimal interface for shell command execution. This is well-scoped for the stated purpose, covering the essential lifecycle without unnecessary bloat.
The tool set covers the full lifecycle of background processes: start (run_background), inspect (list_background), and terminate (kill_background), along with synchronous execution (run). No obvious dead ends or missing operations for a basic bash server.
Maintenance
Related MCP Connectors
I run shell commands on your private cloud environment (bash, sh, zsh)
Remote shell and detached long-running jobs on your own machines — no SSH, open ports or VPN.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables secure execution of shell commands through a dynamic approval system that prompts for user authorization on first use, with persistent command storage and comprehensive audit logging.Apache 2.0
- AlicenseAqualityBmaintenanceEnables execution of bash commands with support for timeouts and background jobs, allowing file operations, build commands, system inspection, and long-running tasks.362275 npm9MIT
- FlicenseAqualityCmaintenanceProvides tools for executing shell commands both synchronously and asynchronously with real-time output streaming and process management capabilities. It enables users to start background tasks, monitor progress, and manage long-running processes via Stdio or HTTP transports.3-
- AlicenseBqualityCmaintenanceEnables system automation and control including command execution, process management, network tools, environment variables, disk usage, and service status.11MIT