# Shell Exec [Health: Active]

**Category:** 🖥️ Command Line  
**Repository:** https://github.com/domdomegg/shell-exec-mcp.git  
**GitHub Stars:** 9  
**npm Downloads (last month):** 247  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/shell-exec

## Description
Execute bash commands with background job support.

## Tools
Capabilities this server exposes over MCP:

- **execute** — Run a command in bash.

Returns stdout, stderr, and exit code. Default timeout is 5 seconds.

For long-running commands, set 'background: true' to run in background and get a job ID. Then use get_status to check on it.

Tips:
- Use background mode for commands that take more than a few seconds
- For file searches, use 'find' or 'grep'
- For file operations, use 'mv', 'rm', 'mkdir -p', 'stat' etc.
- **get_job_status** — Check status of a background job.

Returns stdout/stderr collected so far, exit code (null if still running), and whether the job is still running.

Completed jobs are cleaned up after their status is read.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "shell-exec": {
    "command": "npx",
    "args": ["-y","shell-exec-mcp"]
  }
}
```

## Documentation

## What Shell Exec MCP server does

The Shell Exec MCP server gives an MCP client a way to run bash commands and retrieve the status of jobs started in the background. It is suited to developer workflows where an agent needs to invoke existing command-line tools rather than use a dedicated API integration.

Typical commands include project builds such as `npm run build` and `make`, file-management operations using utilities such as `find`, `grep`, `mv`, `rm`, `mkdir`, and `stat`, and system inspection with commands such as `df`, `ps`, and `env`. The server does not provide separate MCP tools for each of these operations; they are issued as bash commands through `execute`.

## How it works

The Shell Exec MCP server exposes two tools. `execute` runs a bash command and accepts an optional timeout and background mode. A command started in the background can continue while the client performs other work. `get_job_status` checks the state of one of those background jobs later.

This model supports both short operations and tasks that may take longer to finish. For example, a client can run a build in the foreground when it needs the command output immediately, or start a server or watch process in the background and query its status afterward. The available behavior is limited to the command execution and job-status functions described by the project.

## Setup and configuration

Follow the project’s install-mcp setup link to generate the configuration for an MCP client. The provided setup configuration uses `npx` to run the `shell-exec-mcp` package. The README specifically lists Claude Code, Claude Desktop, Cursor, Cline, and VS Code as supported configuration targets, along with other clients.

For development or contribution, the repository requires Git and Node.js. After cloning it, install dependencies with `npm install`. The project documents `npm run test` for running tests and `npm run build` for creating a build. These are repository-development instructions rather than additional MCP tools.

## Tools and capabilities

- `execute`: Runs a bash command, with optional timeout and background execution.
- `get_job_status`: Checks the status of a background job.
- Build and development workflows: Run commands such as `npm run build` or `make`.
- File operations: Use standard bash utilities for finding, moving, removing, creating, or inspecting files.
- System inspection: Run commands such as `df -h`, `ps aux`, or `env`.
- Long-running processes: Start servers or watch processes in background mode and check them later.

## Limitations and notes

The Shell Exec MCP server executes bash commands rather than translating requests into narrowly scoped file, process, or build APIs.

The repository follows semantic versioning, and releases are published to the NPM registry through GitHub Actions after version tags are pushed.

_Full upstream README: https://allmcps.com/mcp/shell-exec/readme_