npm shell-exec-mcpstdioupdated 27d ago
MCP server for executing bash commands with background job support.
What can you do with Shell Exec?
shell-exec-mcp
MCP server for executing bash commands with background job support.
Use Cases
Run build commands: Execute npm run build, make, or other build tools and get the output.
File operations: Use find, grep, mv, rm, mkdir -p, stat etc. for file management.
Long-running tasks: Start servers or watch processes in background mode, check on them later.
System info: Run df -h, ps aux, env etc. to inspect the system state.
Setup
Follow the instructions on install-mcp, which generates the right config for your MCP client (Claude Code, Claude Desktop, Cursor, Cline, VS Code, and more).
Tools
| Tool | Description |
|---|---|
execute |
Run a bash command (with optional timeout and background mode) |
get_job_status |
Check status of a background job |
Contributing
Pull requests are welcomed on GitHub! To get started:
- Install Git and Node.js
- Clone the repository
- Install dependencies with
npm install - Run
npm run testto run tests - Build with
npm run build
Releases
Versions follow the semantic versioning spec.
To release:
- Use
npm version <major | minor | patch>to bump the version - Run
git push --follow-tagsto push with tags - Wait for GitHub Actions to publish to the NPM registry.
Install
Add Shell Exec to your client. Pick the one you use.
claude mcp add shell-exec-mcp -- npx -y shell-exec-mcpcodex mcp add shell-exec-mcp -- npx -y shell-exec-mcpamp mcp add shell-exec-mcp -- npx -y shell-exec-mcp{
"mcpServers": {
"shell-exec-mcp": {
"command": "npx",
"args": [
"-y",
"shell-exec-mcp"
]
}
}
}Add to `claude_desktop_config.json`, then restart Claude Desktop.
{
"mcpServers": {
"shell-exec-mcp": {
"command": "npx",
"args": [
"-y",
"shell-exec-mcp"
]
}
}
}Add to `~/.cursor/mcp.json`, or `.cursor/mcp.json` for a single project.
code --add-mcp '{"name":"shell-exec-mcp","command":"npx","args":["-y","shell-exec-mcp"]}'Or add the block manually to `.vscode/mcp.json` under `servers`.
{
"mcpServers": {
"shell-exec-mcp": {
"command": "npx",
"args": [
"-y",
"shell-exec-mcp"
]
}
}
}Add to `~/.codeium/windsurf/mcp_config.json`.
{
"mcpServers": {
"shell-exec-mcp": {
"command": "npx",
"args": [
"-y",
"shell-exec-mcp"
]
}
}
}Add to `cline_mcp_settings.json` via the MCP Servers panel.
{
"mcpServers": {
"shell-exec-mcp": {
"command": "npx",
"args": [
"-y",
"shell-exec-mcp"
]
}
}
}Add to `~/.gemini/settings.json`.
{
"mcpServers": {
"shell-exec-mcp": {
"type": "local",
"command": "npx",
"args": [
"-y",
"shell-exec-mcp"
],
"tools": [
"*"
]
}
}
}Add to `~/.copilot/mcp-config.json`, or run `/mcp add` inside the CLI.
{
"context_servers": {
"shell-exec-mcp": {
"command": {
"path": "npx",
"args": [
"-y",
"shell-exec-mcp"
]
}
}
}
}Add to your Zed `settings.json`.
npx -y shell-exec-mcpRun `goose configure`, choose **Add Extension → Command-line Extension**, and paste this command.
1 tool
Shell Exec exposes one tool to a connected agent.
- get_job_status
- Check status of a background job
Score
56 / 100
Adequate
- Documentation9/25
- Maintenance25/25
- Trust6/20
- Capability4/15
- Install experience12/15
- Documents what it does and how to connect
- Has a resolvable package or endpoint
- Exposes at least one tool, prompt or resource
- README has substantive content
- Includes a code example
- Documents its configuration
- Mentions credentials or security posture
- Last commit 20 days ago
- Has a release history
- Repository is not archived
- No licence detected
- Namespace verified in the official MCP registry
- Claimed by its owner
- Published under an organisation
- 1 tool(s) documented
- Provides prompt templates
- Provides resources
- 12 documented install method(s)
- Published to a package registry
- Offers a hosted endpoint — no local install
Version history
| Versions | Published |
|---|---|
| 1.2.0Latest | May 3, 2026 |
| 1.1.2 | Feb 23, 2026 |
| 1.1.1 | Dec 28, 2025 |
| 1.1.0 | Dec 28, 2025 |
| 1.0.0 | Dec 14, 2025 |