Shell Exec — Claude Code MCP server: bash commands and background jobs
Gives your agent two tools: run a bash command, check on a background job. Handy for builds, file searches and long-running servers.
claude mcp add --env MCP_TRANSPORT=<MCP_TRANSPORT> --transport stdio shell-exec -- npx -y shell-exec-mcpWhat Shell Exec does
Shell Exec is an MCP server that hands the agent a shell. It exposes two tools. execute runs a bash command, with an optional timeout and a background mode. get_job_status reports on a job you started earlier.
What goes through execute: build steps like npm run build or make, file work with find, grep, mv, rm, mkdir -p, stat, and system checks such as df -h, ps aux, env. Background mode is the reason to pick this one — a dev server or a file watcher starts without blocking the conversation, and you poll it later.
It runs via npx -y shell-exec-mcp, so Node.js and npm have to be present. One thing to weigh: the agent gets arbitrary command execution in your shell, not a sandbox. If your environment variables hold secrets, sort out permissions and isolation first.
What it helps with
- run a build and pull the output back into the chat
- locate files by pattern with
findandgrep - start a dev server in the background and check it later
- inspect disk usage and running processes
- move or delete files straight from the agent
Example prompts for the agent
- Run
npm run buildand show me where it fails - Start
npm run devin the background, then check the job status - Grep the
srcfolder for everyTODO
How to install Shell Exec
Platform CLI
claude mcp add --env MCP_TRANSPORT=<MCP_TRANSPORT> --transport stdio shell-exec -- npx -y shell-exec-mcpReplace <…> with your own values
Platform CLI
codex mcp add shell-exec --env MCP_TRANSPORT=<MCP_TRANSPORT> -- npx -y shell-exec-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"shell-exec": {
"command": "npx",
"args": [
"-y",
"shell-exec-mcp"
],
"env": {
"MCP_TRANSPORT": "<MCP_TRANSPORT>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"shell-exec": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"shell-exec-mcp"
],
"env": {
"MCP_TRANSPORT": "<MCP_TRANSPORT>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e MCP_TRANSPORT=<MCP_TRANSPORT> shell-exec npx -y shell-exec-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Shell Exec
How do I install Shell Exec in Claude Code?
Run claude mcp add shell-exec-mcp -- npx -y shell-exec-mcp. For a transport setting, use claude mcp add --env MCP_TRANSPORT=<MCP_TRANSPORT> --transport stdio shell-exec -- npx -y shell-exec-mcp.
What does Shell Exec do?
It provides the execute tool for bash commands and get_job_status for background jobs. Builds, file searches and background servers all go through those two.
Does Shell Exec need Node.js?
Yes. The server starts with npx -y shell-exec-mcp, so Node.js and npm must be installed. Commands run in your own shell, with no sandbox around them.
