kblood/MCPConsoleServer

MCPConsoleServer - Model Context Protocol Console Server

A C# implementation of the Model Context Protocol (MCP) for console and command execution operations, providing LLMs with the ability to:

• Create persistent console sessions that maintain state between commands
• Execute commands in CMD, PowerShell, and WSL with environment persistence
• Manage system processes and get comprehensive system information
• Handle long-running operations without timeouts (like installations)

🔄 Persistent Sessions - Key Feature

The major advantage: Create console sessions that persist between commands, maintaining:

• ✅ Working directory changes
• ✅ Environment variables
• ✅ Installed software state
• ✅ Session-specific configurations
• ✅ Long-running processes (installations, builds, etc.)

Before vs After

# OLD WAY: Each command is isolated
execute_cmd("cd /d C:\Projects")     # Changes directory
execute_cmd("dir")                   # Back to original directory! ❌

# NEW WAY: Session maintains state
create_session("dev", "CMD")         # Create persistent session
execute_in_session("dev", "cd /d C:\Projects")  # Change directory
execute_in_session("dev", "dir")     # Still in C:\Projects! ✅

⚠️ Security Warning

This MCP server provides powerful system access capabilities. Use with extreme caution!

Security Features

• Command Filtering: Dangerous commands are blocked by default
• Process Protection: Critical system processes cannot be killed
• Session Isolation: Each session runs independently
• Safe Mode: Runs in safe mode by default (dangerous commands disabled)

Enable Dangerous Commands (Use at Your Own Risk)

MCPConsoleServer.exe --allow-dangerous true

Available Tools (29 Total)

🖥️ Session Management (8 tools)

• create_session - Create a persistent console session
• execute_in_session - Execute commands in a session (maintains state!)
• list_sessions - View all active sessions
• get_session_info - Get detailed session information
• close_session - Close a specific session
• cleanup_sessions - Clean up inactive sessions
• get_session_directory - Get current directory of a session
• change_session_directory - Change directory in a session
• execute_batch_in_session - Run multiple commands in sequence

💻 Direct Console Operations (6 tools)

• execute_cmd - Run single CMD commands (non-persistent)
• execute_powershell - Execute PowerShell scripts (non-persistent)
• execute_wsl - Execute Linux commands (non-persistent)
• get_current_directory - Get current working directory
• change_directory - Change working directory
• list_directory - List files and directories

🔧 Process Management (6 tools)

• list_processes - View all running processes
• get_process_info - Get detailed process info
• find_processes - Search processes by name
• kill_process - Terminate processes (with safety checks)
• get_top_processes - Top processes by CPU usage
• get_top_memory_processes - Top processes by memory usage

📊 System Information (9 tools)

• get_system_info - Complete system overview
• check_wsl - WSL availability and distributions
• get_environment_variables - Environment variables
• get_performance_info - CPU, memory, performance metrics
• get_drive_info - Disk space information
• get_powershell_version - PowerShell version
• get_network_info - Network configuration
• get_windows_features - Windows features (admin required)
• get_event_log - System event logs

🚀 Usage Examples

Development Environment Setup

# Create a development session
create_session("dev-env", "PowerShell", workingDirectory="C:\Projects")

# Set up the environment (all in the same session!)
execute_in_session("dev-env", "Set-ExecutionPolicy RemoteSigned -Scope Process")
execute_in_session("dev-env", "cd MyProject")
execute_in_session("dev-env", "npm install")  # Long-running - no timeout!
execute_in_session("dev-env", "dotnet restore")

# Later, continue working in the same environment
execute_in_session("dev-env", "npm run build")
execute_in_session("dev-env", "dotnet run")

Long-Running Installation

# Create session for software installation
create_session("install-node", "CMD")

# Install Node.js (takes several minutes)
execute_in_session("install-node", "winget install OpenJS.NodeJS", timeoutSeconds=0)

# Verify installation in same environment
execute_in_session("install-node", "node --version")
execute_in_session("install-node", "npm --version")

WSL Development Environment

# Create WSL session with specific distribution
create_session("ubuntu-dev", "WSL", wslDistribution="Ubuntu")

# Set up development environment
execute_in_session("ubuntu-dev", "cd /home/user/projects")
execute_in_session("ubuntu-dev", "export NODE_ENV=development")
execute_in_session("ubuntu-dev", "sudo apt update")  # No timeout needed
execute_in_session("ubuntu-dev", "sudo apt install -y docker.io")

# Continue working in the same environment
execute_in_session("ubuntu-dev", "docker --version")

Batch Operations

# Execute multiple commands in sequence
execute_batch_in_session("dev-env", [
    "git pull origin main",
    "npm ci", 
    "npm run test",
    "npm run build"
], stopOnError=true)

🔧 Command Line Options

MCPConsoleServer.exe [options]

Options:
  --allow-dangerous <true|false>  Enable dangerous command execution (default: false)
  --timeout <seconds>             Set default command timeout (default: 30)

Example Usage

# Safe mode with custom timeout
MCPConsoleServer.exe --timeout 60

# Enable dangerous commands (use with caution!)
MCPConsoleServer.exe --allow-dangerous true --timeout 120

📁 Configuration Files

Claude Desktop Configuration

{
  "mcpServers": {
    "console": {
      "command": "path/to/MCPConsoleServer.exe",
      "args": ["--timeout", "60"]
    }
  }
}

mcpo (OpenAPI Proxy) Configuration

# Basic usage
uvx mcpo --port 8000 --api-key "your-key" -- path/to/MCPConsoleServer.exe

# With configuration file
mcpo --config mcpo-config.json --port 8000 --api-key "your-key"

🔐 Security Considerations

Blocked Commands (Default)

• System shutdown/restart commands
• File system destruction commands (rm -rf, format, etc.)
• Registry manipulation
• Network attack tools
• Broad process killing
• Disk formatting operations
• Service manipulation
• Dangerous PowerShell operations

Process Kill Protection

Critical system processes are protected:

• system, smss, csrss, wininit, winlogon
• services, lsass, svchost, dwm, explorer
• Other critical Windows system processes

Session Security

• Each session runs in its own process
• Sessions don't share environment variables
• Command filtering applies to all sessions
• Sessions can be individually terminated

💡 Best Practices

Session Management

1. Use descriptive names: create_session("node-build", "CMD")
2. Clean up when done: close_session("temp-session")
3. Check session status: list_sessions() before executing commands
4. Use appropriate shell: PowerShell for Windows admin, WSL for Linux tools

Long-Running Operations

• Set timeoutSeconds=0 for installations and builds
• Monitor session status during long operations
• Use batch execution for multi-step processes

Security

1. Run in Safe Mode: Keep dangerous commands disabled unless needed
2. Session Isolation: Use separate sessions for different tasks
3. Regular Cleanup: Use cleanup_sessions() to remove dead sessions
4. Monitor Usage: Review session activity regularly

🏗️ Building the Project

# Build and publish
cd MCPConsoleServer
build.bat

# Test the build
test.bat

📦 Dependencies

• .NET 9.0
• ModelContextProtocol SDK
• System.Management (for process management)
• Microsoft.Extensions.Hosting

🎯 Key Advantages

1. Environment Persistence - Sessions maintain state between commands
2. Long-Running Support - No timeouts for installations and builds
3. Multi-Shell Support - CMD, PowerShell, and WSL in persistent sessions
4. Development Workflow - Perfect for development environment setup
5. Session Management - Create, monitor, and manage multiple console environments
6. Security First - Safe by default with override options
7. MCP Compatible - Works with Claude Desktop and mcpo
8. Production Ready - Error handling, session monitoring, and cleanup

Perfect for: Development workflows, software installation, environment setup, system administration, and any task requiring persistent console state! 🚀

⚠️ Important: This tool provides powerful system access. Always review commands before execution and understand the security implications of enabling dangerous operations. Use sessions responsibly and clean up inactive sessions regularly.