Shell Server

CI License: MIT TypeScript Node.js MCP npm

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)

npm install -g @mako10k/mcp-shell-server

After installation, verify the CLI:

mcp-shell-server --version
mcp-shell-server --help

Local Development Installation

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:

npm link
mcp-shell-server --help

Configuration for Popular MCP Clients

Claude Desktop

{
  "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:

{
  "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:

{
  "servers": {
    "mcp-shell-server": {
      "type": "stdio",
      "command": "mcp-shell-server"
    }
  }
}

📚 Detailed Setup Guides | 📁 Configuration 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

# 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

# Start the MCP server
npm start

# Or run in development mode
npm run dev

Using with MCP Client

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:

// 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:

// 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

// 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

// 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

npm start

CLI Usage

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

npm run dev

Build

npm run build

Testing

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

  export MCP_DISABLED_TOOLS="terminal_create,process_terminate"
  

Working Directory Configuration

• MCP_SHELL_DEFAULT_WORKDIR: Set the default working directory for all command executions

  export MCP_SHELL_DEFAULT_WORKDIR="/home/user/projects"
  

• MCP_SHELL_ALLOWED_WORKDIRS: Comma-separated list of allowed working directories

  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)

  export MCP_SHELL_SECURITY_MODE="enhanced"
  

• MCP_SHELL_ELICITATION: Enable user intent elicitation for complex scenarios (for enhanced modes)

  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

  export MCP_SHELL_MAX_EXECUTION_TIME="300"
  

• MCP_SHELL_MAX_MEMORY_MB: Default maximum memory usage in MB

  export MCP_SHELL_MAX_MEMORY_MB="1024"
  

Complete Configuration Example

# 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:

{
  "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:

{
  "command": "ls -la",
  "execution_mode": "foreground"
}

Adaptive execution with intelligent background transition:

{
  "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:

// 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:

{
  "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 Operations

list_execution_outputs

List managed output files with filtering.

read_execution_output

Read output file contents safely.

delete_execution_outputs

Delete output files with confirmation.

Security & Monitoring

security_set_restrictions

Configure security restrictions.

monitoring_get_stats

Get system-wide statistics.

Architecture

mcp-shell-server/
├── src/
│   ├── core/           # Core managers
│   │   ├── process-manager.ts
│   │   ├── terminal-manager.ts
│   │   ├── file-manager.ts
│   │   └── monitoring-manager.ts
│   ├── security/       # Security components
│   │   └── manager.ts
│   ├── tools/          # MCP tool handlers
│   │   └── shell-tools.ts
│   ├── types/          # Type definitions
│   │   ├── index.ts
│   │   └── schemas.ts
│   ├── utils/          # Utilities
│   │   ├── errors.ts
│   │   └── helpers.ts
│   ├── server.ts       # Main MCP server
│   └── index.ts        # Entry point
└── docs/
    └── specification.md

Security Considerations

1. Command Validation: All commands are validated against security policies
2. Path Restrictions: File system access is limited to allowed directories
3. Resource Limits: CPU, memory, and execution time limits are enforced
4. Audit Logging: All operations are logged for security auditing
5. Sandboxed Execution: Commands run in isolated environments

Error Handling

The server provides comprehensive error handling with categorized error codes:

• AUTH_*: Authentication and authorization errors
• PARAM_*: Parameter validation errors
• RESOURCE_*: Resource not found or limit errors
• EXECUTION_*: Command execution errors
• SYSTEM_*: System and internal errors
• SECURITY_*: Security policy violations

Performance

• Concurrent Processes: Up to 50 simultaneous processes
• Terminal Sessions: Up to 20 active terminals
• File Management: Up to 10,000 managed files
• Memory Efficient: Automatic cleanup and garbage collection
• Scalable: Designed for high-throughput operations

Platform Support

• ✅ Linux (Full support)
• ✅ macOS (Full support)
• ⚠️ Windows (Basic support)

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Version History

v2.0.0 (2025-06-13)

• Complete API redesign
• Enhanced security features
• Performance improvements
• New terminal management
• Comprehensive monitoring

Documentation

Core Documentation

• API Specification - Complete API reference
• Control Codes Guide - Terminal control sequences and escape codes
• Program Guard Manual - Security features and process targeting

Examples

• Control Codes Demo - Control code usage examples
• Program Guard Demo - Security feature demonstrations

Getting Started

• Review the API Specification for complete tool documentation
• Check out Control Codes Guide for advanced terminal features
• Learn about Program Guard for enhanced security