MCP Shell Server


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

🚀 Quick Start

$3

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
`

$3

#### 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 | 📁 Configuration Examples

🎉 Status: Production Ready

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

$3

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

$3

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

$3

- Sandboxed command execution
- Configurable command restrictions
- Path access control
- Resource usage limits
- Real-time security monitoring

$3

- 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

$3

- 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

$3

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

$3

- 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

$3

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

$3

`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);
`

$3

#### 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
}
}
});
`

$3

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

$3

`bash
npm start
`

$3

`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

$3

`bash
npm run dev
`

$3

`bash
npm run build
`

$3

`bash
npm test
`

Configuration

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

$3

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

$3


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.

$3

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.

$3

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

$3

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

$3

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

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

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

$3

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

$3

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

$3

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

$3

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

Documentation

$3

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

$3

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

$3

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