Shell Exec

You have an MCP server that lets you execute bash commands and manage them as background jobs. It’s useful for running builds, performing file operations, handling long-running tasks, and inspecting system state from a consistent API.

How to use

To use this MCP server, you connect your MCP client and send commands that are executed on the server side. You can run short commands, start long-running processes in the background, and check the status of those jobs later. Use the provided tools to start a process, monitor it, or query system information and file operations. All actions are exposed through the MCP endpoints so you can orchestrate builds, maintenance tasks, and diagnostics from your automation scripts.

How to install

Prerequisites: you need Node.js and npm installed on your machine.

claude mcp add shell-exec-mcp -- npx -y shell-exec-mcp

Or with HTTP transport:

# Start the server
MCP_TRANSPORT=http PORT=3000 npx -y shell-exec-mcp

# Add to Claude
claude mcp add --transport http shell-exec-mcp http://localhost:3000/mcp

Additional configuration and usage notes

This MCP server provides two connection methods for you to choose from. The HTTP method uses a remote URL to communicate with the server, while the stdio method runs the server locally as a background process and is started with a command you provide.

Examples of what you can do with this MCP server

- Run build commands like npm run build, make, or other build tools and capture their output.
- Perform file operations with commands such as find, grep, mv, rm, mkdir -p, and stat.
- Launch long-running tasks in the background (servers or watchers) and check on them later.
- Gather system information with df -h, ps aux, env, and related commands.

Command and tool overview

Tools exposed by this MCP server include:

• execute: Run a bash command with optional timeout and background mode
• get_job_status: Check the status of a background job and retrieve its results or logs.

Sample MCP configuration

{
  "mcpServers": {
    "shell_exec_mcp_http": {
      "type": "http",
      "name": "shell_exec_mcp",
      "url": "http://localhost:3000/mcp",
      "args": []
    },
    "shell_exec_mcp_stdio": {
      "type": "stdio",
      "name": "shell_exec_mcp",
      "command": "npx",
      "args": ["-y", "shell-exec-mcp"]
    }
  },
  "envVars": []
}

Available tools

execute

Run a bash command with optional timeout and background mode to execute tasks and capture output.

get_job_status

Check the status of a background job and retrieve its output or progress.