guangxiangdebizi/windows-system-mcp

🖥️ Windows System MCP

A comprehensive Model Context Protocol (MCP) server that provides AI models with powerful Windows system management capabilities. This MCP enables AI assistants to interact with Windows systems through a secure, well-structured interface.

✨ Features

📁 File System Management

• Directory Browsing: Navigate and explore directory structures
• File Operations: Read files, get file information, and search for files
• Disk Analysis: Monitor disk usage and find large files
• Advanced Search: Pattern-based file searching with recursive options

⚙️ Process Management

• Process Monitoring: List and monitor running processes
• Resource Tracking: Track CPU and memory usage by process
• Process Control: Start, stop, and manage processes
• Process Tree: Visualize parent-child process relationships

🔧 System Information

• Hardware Details: CPU, memory, disk, and network adapter information
• OS Information: Windows version, updates, and system configuration
• Environment: Environment variables and system paths
• User Management: User accounts and current user information

📋 Registry Operations

• Registry Reading: Access Windows registry keys and values
• System Configuration: Retrieve system settings from registry
• Startup Programs: List programs that start with Windows
• Installed Software: Enumerate installed applications

🛠️ Service Management

• Service Control: Start, stop, and restart Windows services
• Service Monitoring: Monitor service status and dependencies
• Startup Services: Manage services that start automatically
• Service Search: Find services by name or description

🌐 Network Operations

• Network Diagnostics: Ping, traceroute, and connectivity testing
• Port Scanning: Check open ports and network connections
• Network Configuration: View adapters, IP configuration, and routing
• WiFi Management: List and manage WiFi profiles

📊 Performance Monitoring

• Real-time Metrics: CPU, memory, disk, and network performance
• Resource Analysis: Identify top resource-consuming processes
• Performance Counters: Access Windows performance counters
• System Health: Monitor overall system performance

📥 Installation

# Global installation (recommended)
npm install -g windows-system-mcp

# Or use directly with npx
npx windows-system-mcp

🚀 Quick Start

Prerequisites

• Windows 10/11
• Node.js 18+
• PowerShell 5.1+

Installation Options

Option 1: Install from NPM (Recommended)

npm install -g windows-system-mcp

Option 2: Build from Source

1. Clone the repository:

   git clone https://github.com/guangxiangdebizi/windows-system-mcp.git
   cd windows-system-mcp
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Local Development (Stdio)

If installed globally:

windows-system-mcp

If built from source:

npm start

Development

For development with auto-rebuild:

npm run dev

SSE Deployment (Supergateway)

If installed globally:

npx supergateway --stdio "windows-system-mcp" --port 3100

If built from source:

npm run sse

This will start the server on http://localhost:3100/sse

🔧 Configuration

Claude Desktop Integration

Stdio Configuration

If installed globally:

{
  "mcpServers": {
    "windows-system-mcp": {
      "command": "windows-system-mcp"
    }
  }
}

If built from source:

{
  "mcpServers": {
    "windows-system-mcp": {
      "command": "node",
      "args": ["path/to/windows-system-mcp/build/index.js"]
    }
  }
}

SSE Configuration

{
  "mcpServers": {
    "windows-system-mcp": {
      "type": "sse",
      "url": "http://localhost:3100/sse",
      "timeout": 600
    }
  }
}

Note: For SSE mode, start the server first using the commands shown in the deployment section above.

📖 Usage Examples

File System Operations

// List directory contents
{
  "action": "list_directory",
  "path": "C:\\Users",
  "recursive": true,
  "max_depth": 2
}

// Search for files
{
  "action": "search_files",
  "pattern": "*.log",
  "path": "C:\\Windows\\Logs",
  "recursive": true
}

// Find large files
{
  "action": "find_large_files",
  "path": "C:\\",
  "size_threshold": 500
}

Process Management

// List running processes
{
  "action": "list_processes",
  "sort_by": "cpu",
  "limit": 20
}

// Get process details
{
  "action": "get_process_details",
  "process_name": "chrome"
}

// Kill a process
{
  "action": "kill_process",
  "process_id": 1234
}

System Information

// Get system overview
{
  "action": "get_system_overview"
}

// Get hardware information
{
  "action": "get_hardware_info",
  "category": "cpu"
}

// Get environment variables
{
  "action": "get_environment_vars",
  "filter": "PATH"
}

Network Operations

// Ping a host
{
  "action": "ping_host",
  "host": "google.com",
  "count": 4
}

// Scan ports
{
  "action": "scan_open_ports",
  "host": "localhost",
  "port_range": "80,443,3000-3010"
}

// Get network adapters
{
  "action": "get_network_adapters"
}

🛡️ Security Considerations

• Principle of Least Privilege: Run with minimal required permissions
• Input Validation: All inputs are validated and sanitized
• Safe Operations: Read-only operations are prioritized
• Error Handling: Comprehensive error handling prevents system exposure
• Audit Trail: All operations can be logged for security auditing

🤝 Contributing

We welcome contributions! Please see our for details.

Development Setup

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Add tests if applicable
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

📄 License

This project is licensed under the Apache License 2.0 - see the file for details.

🔗 Links

• NPM Package: https://www.npmjs.com/package/windows-system-mcp
• GitHub: https://github.com/guangxiangdebizi/windows-system-mcp
• Author: Xingyu Chen
• Email: guangxiangdebizi@gmail.com
• NPM Profile: https://www.npmjs.com/~xingyuchen

👨‍💻 Author

Xingyu Chen

• 🌐 Website: GitHub Profile
• 📧 Email: guangxiangdebizi@gmail.com
• 💼 LinkedIn: Xingyu Chen
• 📦 NPM: @xingyuchen

🙏 Acknowledgments

• Model Context Protocol for the excellent MCP framework
• The Windows PowerShell team for providing powerful system management capabilities
• The TypeScript and Node.js communities for excellent tooling

📊 Project Stats

• NPM Package: Available as windows-system-mcp
• Language: TypeScript
• Runtime: Node.js
• Platform: Windows
• License: Apache 2.0
• MCP Version: 0.6.0