# bash-command MCP server

> Executes shell commands with advanced background process orchestration and observability for AI agents.

- Repository: https://github.com/mrorigo/bash-command-mcp
- Page: https://hostedmcp.org/servers/mrorigo/bash-command-mcp
- Transport: stdio
- Stars: 3
- License: MIT
- Latest version: 1.0.0

## Install

### Claude Code

```sh
claude mcp add bash-command-mcp -- npx -y bash-command-mcp
```

### Cursor (`~/.cursor/mcp.json`)

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

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "bash-command-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "bash-command-mcp"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"bash-command-mcp","type":"stdio","command":"npx","args":["-y","bash-command-mcp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

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

### Codex

```sh
codex mcp add bash-command-mcp -- npx -y bash-command-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.bash-command-mcp]
command = "npx"
args = ["-y", "bash-command-mcp"]
```

### Gemini CLI

```sh
gemini mcp add -s user bash-command-mcp npx -- -y bash-command-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

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

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `BASH_COMMAND_MCP_HOST` | no | no |  |
| `BASH_COMMAND_MCP_LOG_DIR` | no | no | Directory used to store background process stdout/stderr log files. |
| `BASH_COMMAND_MCP_PORT` | no | no |  |
| `BASH_COMMAND_MCP_TRANSPORT` | no | no |  |
| `OTEL_ENABLED` | no | no | Enable or disable OpenTelemetry instrumentation (`true` or `false`). |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | no | no | OTLP HTTP endpoint for exporting OpenTelemetry traces and metrics (for example `http://localhost:4318`). |
| `OTEL_METRIC_EXPORT_INTERVAL_MS` | no | no | OpenTelemetry metrics export interval in milliseconds. |
| `OTEL_SERVICE_NAME` | no | no | OpenTelemetry service name override. |
| `OTEL_SERVICE_VERSION` | no | no | OpenTelemetry service version override. |

## Tools (6)

- `run`
- `run_background`
- `list_background`
- `kill_background`
- `tail_background`
- `wait_background`

## FAQ

### Is it safe to run this server on my host machine?

It is recommended to use Docker to isolate execution because the server executes shell commands with your user permissions.

### Can I run commands in the background?

Yes, the server provides tools to start, list, kill, tail, and wait for background processes.

### How can I monitor the server's performance and traces?

The server includes built-in OpenTelemetry instrumentation for traces and metrics.

### What transport methods are supported?

The server supports stdio for local integrations and Streamable HTTP for remote or network-accessible clients.