Winsight MCP

🚀 WinSight MCP

WinSight MCP is an MCP server that enables Claude Code to capture the screen, manage windows, and launch applications on Windows.

🚀 Quick Start

Option 1: uvx (recommended)

No installation is required; it can run directly. Add the following to your project's .mcp.json or ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "winsight": {
      "command": "uvx",
      "args": ["winsight-mcp"]
    }
  }
}

Option 2: pip install

First, install the package using the following command:

pip install winsight-mcp

Then, configure it as follows:

{
  "mcpServers": {
    "winsight": {
      "command": "winsight-mcp"
    }
  }
}

Option 3: From source

Clone the repository, navigate to the directory, and synchronize:

git clone https://github.com/TheoEwzZer/WinSight-MCP.git
cd WinSight-MCP
uv sync

Configure the server as follows:

{
  "mcpServers": {
    "winsight": {
      "command": "uv",
      "args": ["--directory", "/path/to/WinSight-MCP", "run", "winsight-mcp"]
    }
  }
}

✨ Features

• Screenshot: Capture the full screen, a specific region, or a specific window.
• Window capture: Utilize the Win32 PrintWindow API to capture the real window content, even when it's behind other windows.
• List and inspect: List and inspect open windows and monitors, including details such as title, position, size, state, and resolution.
• Control windows: Perform operations like moving, resizing, minimizing, maximizing, restoring, and focusing on windows.
• Launch: Launch applications and wait for their windows to appear.

📦 Installation

Requirements

• Windows 10/11
• Python 3.10+

💻 Usage Examples

Once the MCP server is connected, you can ask Claude Code questions like:

• "Take a screenshot of my screen"
• "List all open windows"
• "Capture the Notepad window"
• "Open calculator and take a screenshot of it"
• "Focus the Chrome window"
• "Resize the app window to 800x600 and take a screenshot"
• "Move the window to the top-left corner"
• "What monitors do I have?"

📚 Documentation

Tools

Screenshot

Window Management

System

🔧 Technical Details

Testing

The project has 112 tests covering all modules. Tests use mocks for Win32 APIs so they can run on any platform.

Running tests

uv run pytest

Test structure

tests/
  conftest.py              # Shared fixtures and Win32 stubs
  test_types.py            # TypedDict definitions validation
  test_screenshot.py       # Screen/region/window capture (mss, Win32 DC)
  test_window_manager.py   # Window listing, find, focus, resize, move, min/max/restore
  test_process_manager.py  # Application launch and window polling
  test_server.py           # MCP tool registration and integration

Adding tests

1. Place new tests in the corresponding test_<module>.py file.
2. Use the shared fixtures from conftest.py (sample_window_info, mcp_server, fake_png_bytes).
3. Mock Win32 APIs with @patch("winsight_mcp.<module>.win32gui"); never call real Win32 functions in tests.
4. For server integration tests, use the _call helper to invoke tools and _text to extract string results.

📄 License

MIT