# Mcp Shell Server

> Secure Model Context Protocol server for shell operations and terminal management

- **Type:** MCP server
- **Install:** `agentstack add mcp-mako10k-mcp-shell-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mako10k](https://agentstack.voostack.com/s/mako10k)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [mako10k](https://github.com/mako10k)
- **Source:** https://github.com/mako10k/mcp-shell-server

## Install

```sh
agentstack add mcp-mako10k-mcp-shell-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MCP Shell Server

[](https://github.com/mako10k/mcp-shell-server/actions)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](https://modelcontextprotocol.io/)
[](https://www.npmjs.com/package/@mako10k/mcp-shell-server)

A secure and comprehensive Model Context Protocol (MCP) server for shell operations, terminal management, and process control.

## 🚀 Quick Start

### Installation

Choose your preferred installation method:

#### Global Installation (Recommended)
```bash
npm install -g @mako10k/mcp-shell-server
```

After installation, verify the CLI:
```bash
mcp-shell-server --version
mcp-shell-server --help
```

#### Local Development Installation
```bash
git clone https://github.com/mako10k/mcp-shell-server.git
cd mcp-shell-server
npm install
npm run build
```

You can also link locally for user-level usage without sudo:
```bash
npm link
mcp-shell-server --help
```

### Configuration for Popular MCP Clients

#### Claude Desktop
```json
{
  "mcpServers": {
    "mcp-shell-server": {
      "command": "mcp-shell-server"
    }
  }
}
```

*Note: After global installation, you can use `mcp-shell-server` directly or `npx @mako10k/mcp-shell-server`*

#### VS Code with GitHub Copilot
Create `.vscode/mcp.json`:
```json
{
  "servers": {
    "mcp-shell-server": {
      "type": "stdio",
      "command": "mcp-shell-server",
      "env": {
        "MCP_SHELL_SECURITY_MODE": "enhanced",
        "MCP_SHELL_ELICITATION": "true"
      }
    }
  }
}
```

#### Cursor
Add to MCP settings:
```json
{
  "servers": {
    "mcp-shell-server": {
      "type": "stdio",
      "command": "mcp-shell-server"
    }
  }
}
```

📚 **[Detailed Setup Guides](docs/setup/)** | 📁 **[Configuration Examples](examples/)**

## 🎉 Status: Production Ready

✅ **COMPLETE** - The MCP Shell Server is fully implemented and ready for production use.

### Build Status
- ✅ TypeScript compilation successful
- ✅ All strict type checking passed
- ✅ Security validation working
- ✅ Core managers operational
- ✅ MCP integration complete

### Key Achievements
- 🔐 **Comprehensive Security**: Advanced command validation and sandboxing
- 🖥️ **18 MCP Tools**: Complete API covering all shell operations
- 📊 **Real-time Monitoring**: System and process metrics
- 🖥️ **Terminal Sessions**: Interactive PTY-based terminals
- 📁 **File Management**: Secure file operations and storage
- 🔌 **MCP Standards**: Full Model Context Protocol compliance

## Features

### 🛡️ Security-First Design
- Sandboxed command execution
- Configurable command restrictions
- Path access control
- Resource usage limits
- Real-time security monitoring

### 🔧 Shell Operations
- Multiple execution modes: foreground, background, detached, adaptive
- **🆕 Pipeline Feature**: Command chaining with `input_output_id` parameter
- **🆕 Intelligent Guidance**: Adaptive mode provides usage hints when commands transition to background
- Background process management with timeout handling
- Configurable timeouts and output limits
- Environment variable control
- Input/output capture and partial output support

### 💻 Terminal Management
- Interactive terminal sessions
- Multiple shell support (bash, zsh, fish, PowerShell)
- **🆕 Control Code Support**: Send control characters and escape sequences
- **🆕 Program Guard**: Secure input targeting with process validation
- **🆕 Foreground Process Detection**: Real-time process information
- Resizable terminals
- Command history
- Real-time output streaming

### 🔐 Advanced Security Features
- **🆕 Enhanced Safety Evaluator**: AI-powered command safety analysis
  - LLM-based security evaluation with detailed reasoning
  - Context-aware risk assessment
  - Intelligent alternative suggestions
  - Built-in user intent elicitation for complex scenarios
- **🆕 Program Guard System**: Prevents unintended input delivery
  - Target specific processes by name, path, or PID
  - Session leader detection and validation
  - Safe fallback behavior for unknown processes
- **🆕 Control Code Validation**: Secure handling of terminal control sequences
- Process isolation and sandboxing
- Configurable security restrictions

### 📁 File Operations
- Output file management
- **🆕 Automatic Cleanup**: Smart suggestions for old file cleanup with configurable retention policies
- **🆕 Storage Analysis**: Real-time disk usage monitoring and optimization recommendations
- Log file handling
- Temporary file storage
- Safe file reading with encoding support
- Batch file operations

### 📊 Monitoring & Statistics
- Real-time process monitoring
- System resource tracking
- Performance metrics
- Usage statistics
- Health monitoring

## Installation

```bash
# Clone the repository
git clone https://github.com/mako10k/mcp-shell-server.git
cd mcp-shell-server

# Install dependencies
npm install

# Build the project
npm run build
```

## Quick Start

```bash
# Start the MCP server
npm start

# Or run in development mode
npm run dev
```

### Using with MCP Client

```typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'node',
  args: ['dist/index.js']
});

const client = new Client(
  { name: 'mcp-client', version: '1.0.0' },
  { capabilities: {} }
);

await client.connect(transport);

// Execute a shell command
const result = await client.request({
  method: 'tools/call',
  params: {
    name: 'shell_execute',
    arguments: {
      command: 'echo "Hello from MCP Shell Server!"',
      execution_mode: 'foreground'
    }
  }
});

console.log(result);
```

### 🆕 New Features in v2.1.8

#### Intelligent Command Guidance
Automatic guidance when commands transition to background execution:
```typescript
// When a command times out or exceeds size limits, get helpful guidance
const result = await client.request({
  method: 'tools/call',
  params: {
    name: 'shell_execute',
    arguments: {
      command: 'find /usr -name "*.so"',
      execution_mode: 'adaptive',
      max_output_size: 1024
    }
  }
});

// Response includes guidance for pipeline processing
console.log(result.guidance.pipeline_usage);
// "Background process active. Use "input_output_id": "xyz" for real-time processing"
```

#### Automatic File Cleanup
Smart cleanup suggestions and automated maintenance:
```typescript
// Get cleanup suggestions
const suggestions = await client.request({
  method: 'tools/call',
  params: {
    name: 'get_cleanup_suggestions',
    arguments: {
      max_age_hours: 24,
      max_size_mb: 50
    }
  }
});

// Perform automatic cleanup with retention policies
const cleanup = await client.request({
  method: 'tools/call',
  params: {
    name: 'perform_auto_cleanup',
    arguments: {
      dry_run: false,
      max_age_hours: 24,
      preserve_recent: 10
    }
  }
});
```

### 🆕 Previous Features in v2.1.0

#### Control Code Support
```typescript
// Send Ctrl+C to interrupt a process
await client.request({
  method: 'tools/call',
  params: {
    name: 'terminal_send_input',
    arguments: {
      terminal_id: 'terminal_123',
      input: '^C',
      control_codes: true
    }
  }
});

// Send ANSI escape sequences for colored output
await client.request({
  method: 'tools/call',
  params: {
    name: 'terminal_send_input',
    arguments: {
      terminal_id: 'terminal_123',
      input: '\\x1b[31mRed Text\\x1b[0m',
      control_codes: true
    }
  }
});
```

#### Program Guard Security
```typescript
// Only allow input to bash processes
await client.request({
  method: 'tools/call',
  params: {
    name: 'terminal_send_input',
    arguments: {
      terminal_id: 'terminal_123',
      input: 'echo "secure command"',
      send_to: 'bash',
      execute: true
    }
  }
});

// Target specific process by PID
await client.request({
  method: 'tools/call',
  params: {
    name: 'terminal_send_input',
    arguments: {
      terminal_id: 'terminal_123',
      input: '^C',
      send_to: 'pid:12345',
      control_codes: true
    }
  }
});
```

## Usage

### Basic Usage

```bash
npm start
```

### CLI Usage

```bash
mcp-shell-server --help
mcp-shell-server --version
```

The server supports various environment variables (see sections below), such as:
- `BACKOFFICE_ENABLED`, `BACKOFFICE_PORT`
- `EXECUTION_BACKEND` and `EXECUTOR_*` for remote executor
- `MCP_SHELL_DEFAULT_WORKDIR`, `MCP_SHELL_ALLOWED_WORKDIRS`
- `MCP_DISABLED_TOOLS`, `LOG_LEVEL`

### Development

```bash
npm run dev
```

### Build

```bash
npm run build
```

### Testing

```bash
npm test
```

## Configuration

The server can be configured through environment variables or by calling the security restriction tools at runtime.

### Default Security Settings

- Blocked dangerous commands (rm, sudo, etc.)
- Limited to safe directories
- 5-minute execution timeout
- 1GB memory limit

### Disabling Tools
Set `MCP_DISABLED_TOOLS` to a comma-separated list of tool names to disable.
Disabled tools will not appear in the tool list and cannot be called.

### Environment Variables

The server supports the following environment variables for configuration:

#### General Configuration
- `MCP_DISABLED_TOOLS`: Comma-separated list of tool names to disable
  ```bash
  export MCP_DISABLED_TOOLS="terminal_create,process_terminate"
  ```

#### Working Directory Configuration
- `MCP_SHELL_DEFAULT_WORKDIR`: Set the default working directory for all command executions
  ```bash
  export MCP_SHELL_DEFAULT_WORKDIR="/home/user/projects"
  ```
- `MCP_SHELL_ALLOWED_WORKDIRS`: Comma-separated list of allowed working directories
  ```bash
  export MCP_SHELL_ALLOWED_WORKDIRS="/home/user,/tmp,/var/log"
  ```

#### Security Configuration
- `MCP_SHELL_SECURITY_MODE`: Set the default security mode (`permissive`, `restrictive`, `enhanced`, `enhanced-fast`, or `custom`)
  ```bash
  export MCP_SHELL_SECURITY_MODE="enhanced"
  ```
- `MCP_SHELL_ELICITATION`: Enable user intent elicitation for complex scenarios (for enhanced modes)
  ```bash
  export MCP_SHELL_ELICITATION="true"
  ```
- `MCP_SHELL_LLM_API_KEY`: API key for LLM-based safety evaluation (optional, falls back to MCP sampling)
- `MCP_SHELL_LLM_TIMEOUT`: Timeout for LLM evaluation in seconds (default: 30)

#### Resource Limits
- `MCP_SHELL_MAX_EXECUTION_TIME`: Default maximum execution time in seconds
  ```bash
  export MCP_SHELL_MAX_EXECUTION_TIME="300"
  ```
- `MCP_SHELL_MAX_MEMORY_MB`: Default maximum memory usage in MB
  ```bash
  export MCP_SHELL_MAX_MEMORY_MB="1024"
  ```

#### Complete Configuration Example
```bash
# Security settings
export MCP_SHELL_SECURITY_MODE="restrictive"
export MCP_SHELL_MAX_EXECUTION_TIME="300"
export MCP_SHELL_MAX_MEMORY_MB="1024"

# Working directory settings
export MCP_SHELL_DEFAULT_WORKDIR="/home/user/projects"
export MCP_SHELL_ALLOWED_WORKDIRS="/home/user,/tmp"

# Tool restrictions
export MCP_DISABLED_TOOLS="process_terminate,delete_execution_outputs"

# Start the server
npm start
```

**Note**: Additional configuration options can be set at runtime using the `security_set_restrictions` tool for more granular control over allowed/blocked commands, directories, and other security parameters.

### Runtime Security Configuration

Use the `security_set_restrictions` tool to dynamically configure security settings:

```json
{
  "security_mode": "custom",
  "allowed_commands": ["ls", "cat", "grep"],
  "blocked_commands": ["rm", "sudo"],
  "allowed_directories": ["/tmp", "/home/user"],
  "max_execution_time": 300,
  "max_memory_mb": 1024
}
```

**Security Modes:**
- `permissive`: Allow most commands with basic safety checks
- `restrictive`: Only allow read-only commands (ls, cat, grep, etc.)
- `enhanced`: AI-powered safety evaluation with LLM-based analysis (recommended)
- `enhanced-fast`: Optimized enhanced mode for better performance
- `custom`: Use detailed configuration with allowed/blocked commands

## API Reference

### Shell Operations

#### `shell_execute`
Execute shell commands with various execution modes. Can also create new interactive terminal sessions.

**Parameters:**
- `command` (required): Command to execute
- `execution_mode`: Execution strategy for the command:
  - `'foreground'`: Wait for command completion within timeout_seconds. Best for quick commands
  - `'background'`: Run asynchronously, monitor via process_list. Best for long-running processes
  - `'detached'`: Fire-and-forget execution, minimal monitoring. Best for independent processes
  - `'adaptive'` (default): Start foreground for foreground_timeout_seconds, then switch to background if needed. Best for unknown execution times
- `input_output_id`: Use output from another command as input (Pipeline feature)
- `working_directory`: Working directory
- `environment_variables`: Environment variables
- `timeout_seconds`: Maximum execution timeout (all modes respect this limit)
- `foreground_timeout_seconds`: For adaptive mode: initial foreground phase timeout (default: 10s)
- `return_partial_on_timeout`: Return partial output on timeout
- `max_output_size`: Maximum output size
- `create_terminal`: Create new interactive terminal session
- `terminal_shell`: Shell type for new terminal ('bash', 'zsh', 'fish', etc.)
- `terminal_dimensions`: Terminal dimensions {width, height}

**Examples:**

Regular command execution:
```json
{
  "command": "ls -la",
  "execution_mode": "foreground"
}
```

Adaptive execution with intelligent background transition:
```json
{
  "command": "long-running-process",
  "execution_mode": "adaptive",
  "foreground_timeout_seconds": 10,
  "timeout_seconds": 300,
  "return_partial_on_timeout": true
}
```

**Pipeline Feature - Command Chaining:**
The MCP Shell Server supports command chaining through the Pipeline feature, allowing output from one command to be used as input for another command:

```json
// Step 1: Execute first command and get output_id
{
  "command": "cat input.txt",
  "execution_mode": "foreground"
}
// Response includes: "output_id": "abc123..."

// Step 2: Use output from first command as input for second command
{
  "command": "grep 'pattern'",
  "execution_mode": "foreground",
  "input_output_id": "abc123..."
}
```

**Important Notes:**
- Pipeline feature is different from shell pipes (`|`)
- Each command requires a separate `shell_execute` call
- Use `output_id` from first command's response as `input_output_id` for second command
- FileManager automatically handles data transfer between commands
- Supports large output files (up to 100MB)

**Adaptive Mode Features:**
- Automatically transitions to background when `foreground_timeout_seconds` is reached
- Transitions to background when `max_output_size` is reached (for efficiency)
- Returns `transition_reason` in response: `"foreground_timeout"` or `"output_size_limit"`
- Captures partial output during transitions and saves to FileManager
- Single process execution (no duplicate commands)
- Respects total `timeout_seconds` limit for background phase

Create new terminal session:
```json
{
  "command": "vim file.txt", 
  "create_terminal": true,
  "terminal_shell": "bash",
  "terminal_dimensions": {"width": 120, "height": 40}
}
```

#### `process_get_execution`
Get detailed information about a command execution.

#### `shell_set_default_workdir`
Set the default working directory for command execution.

### Process Management

#### `process_list`
List running processes with filtering options.

#### `process_terminate`
Safely terminate processes with signal control.

#### `process_monitor`
Start real-time process monitoring.

### Terminal Management

#### `terminal_create`
Create interactive terminal sessions.

#### `terminal_send_input`
Send input to terminals.

#### `terminal_get_output`
Get terminal output with ANSI support.

#### `terminal_get_info`
Get detailed terminal information.

#### `terminal_resize`
Resize terminal dimensions.

#### `terminal_close`
Close terminal sessions.

### File Oper

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mako10k](https://github.com/mako10k)
- **Source:** [mako10k/mcp-shell-server](https://github.com/mako10k/mcp-shell-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-mako10k-mcp-shell-server
- Seller: https://agentstack.voostack.com/s/mako10k
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.