NutJS Windows Control

A Windows control server built using nut.js and Model Context Protocol (MCP), providing programmatic control over Windows system operations including mouse, keyboard, window management, and screen capture functionality.

Note: While this project may work on Linux and macOS, it has only been tested on Windows. Community feedback on cross-platform compatibility is welcome.

⚠️ IMPORTANT DISCLAIMER

THIS SOFTWARE IS EXPERIMENTAL AND POTENTIALLY DANGEROUS

By using this software, you acknowledge and accept that:

Giving AI models direct control over your computer through this tool is inherently risky
This software can control your mouse, keyboard, and other system functions which could potentially cause unintended consequences
You are using this software entirely at your own risk
The creators and contributors of this project accept NO responsibility for any damage, data loss, or other consequences that may arise from using this software
This tool should only be used in controlled environments with appropriate safety measures in place

USE AT YOUR OWN RISK

Features

Window Management
- List all windows
- Get active window information
- Get window titles
- Get window size and position
- Focus windows
- Resize windows
- Reposition windows
Mouse Control
- Mouse movement with configurable speed
- Click operations
- Scroll functionality
- Drag operations
- Cursor position tracking
Keyboard Control
- Text input
- Key combinations
- Key press/release operations
- Hold key functionality
Screen Operations
- Screen capture
- Screen size retrieval
- Active window detection
Clipboard Integration
- Get clipboard content
- Set clipboard content
- Clear clipboard
- Check clipboard state

Installation

Clone the repository:

git clone https://github.com/Cheffromspace/nutjs-windows-control.git
cd nutjs-windows-control

Build libnut-core from source (required if you don't have a paid NutJS license):

# Install cmake-js globally (required for building)
npm install -g cmake-js

# Clone libnut repository in a parallel directory
cd ..
git clone https://github.com/nut-tree/libnut.git libnut-core
cd libnut-core

# Install dependencies and build
npm install
cmake-js rebuild

# Return to the main project
cd ../nutjs-windows-control

Install dependencies:

npm install

Build the project:

npm run build

Usage

Starting the Server

npm start

For development with auto-recompilation:

npm run dev

Running Tests

Run all tests:

npm test

Watch mode for development:

npm run test:watch

Generate coverage report:

npm run test:coverage

MCP Server Configuration

To use this project with Claude, add the following configuration to your MCP servers:

{
  "mcpServers": {
    "windows-control": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "[INSTALL LOCATION]\\nutjs-windows-control\\build\\index.js"
      ]
    }
  }
}

After configuring your MCP server, restart Claude to see the windows-control service in the menu.

Project Structure

/src
- /handlers - Request handlers and tool management
- /tools - Core functionality implementations
- /types - TypeScript type definitions
- index.ts - Main application entry point

Dependencies

@modelcontextprotocol/sdk - MCP SDK for protocol implementation
@nut-tree/libnut - Core native UI automation library
clipboardy - Cross-platform clipboard handling
express - Web server framework
jimp & sharp - Image processing

Testing

The project currently includes unit tests for core functionality. The following test areas are planned for future development:

Integration tests for cross-module functionality
Performance testing
Error handling validation

Known Limitations

Window minimize/restore operations are currently unsupported in libnut-core
Advanced screen information (multiple monitors, DPI settings) is limited to main display
Some operations may require elevated permissions depending on the target application
Cross-platform support (Linux/macOS) is untested

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.