Computer Split Screen MCP
Model Context Protocol Server via Cross-Platform (Mac & Windows) Split Screen Functions
Installation
npx computer-split-screen-mcpAsk AI about Computer Split Screen MCP
Powered by Claude Β· Grounded in docs
I know everything about Computer Split Screen MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Computer Split Screen MCP
A high-performance, cross-platform Model Context Protocol (MCP) server that provides reliable split-screen window management for both Windows and macOS. This server exposes 16 window manipulation tools through the MCP protocol, enabling AI assistants and other MCP clients to control desktop window layouts with precision.
π Features
- Cross-platform support: Windows and macOS with native optimizations
- 16 window management tools: Comprehensive split-screen layouts and controls
- High performance: Windows: 15-60ms, macOS: 50-150ms per operation
- Reliability first: Robust fallback mechanisms and error handling
- MCP integration: Full Model Context Protocol server support via stdio transport
- Smart focus detection: Advanced window focus detection with platform-specific optimizations
π οΈ Installation
Prerequisites
- Python: 3.9 or higher
- Package Manager:
uvx(recommended) orpip
Install via uvx (Recommended)
uvx install computer-split-screen-mcp
Install via pip
pip install computer-split-screen-mcp
π§ MCP Client Configuration
Configure your MCP client with the following settings:
{
"mcpServers": {
"computer-split-screen": {
"command": "uvx",
"args": ["computer-split-screen-mcp"],
"env": {}
}
}
}
Alternative Configuration (if not using uvx)
{
"mcpServers": {
"computer-split-screen": {
"command": "python",
"args": ["-m", "computer-split-screen-mcp"],
"env": {}
}
}
}
π― Available Tools
Split-Screen Layouts
Halves (2-way splits)
left-half-screen- Snap current window to left halfright-half-screen- Snap current window to right halftop-half-screen- Snap current window to top halfbottom-half-screen- Snap current window to bottom half
Quadrants (4-way splits)
top-left-screen- Top-left quadrant (1/4 screen)top-right-screen- Top-right quadrant (1/4 screen)bottom-left-screen- Bottom-left quadrant (1/4 screen)bottom-right-screen- Bottom-right quadrant (1/4 screen)
Thirds (3-way splits)
left-one-third-screen- Left third (1/3 screen)middle-one-third-screen- Middle third (1/3 screen)right-one-third-screen- Right third (1/3 screen)
Two-Thirds (2/3 splits)
left-two-thirds-screen- Left two-thirds (2/3 screen)right-two-thirds-screen- Right two-thirds (2/3 screen)
Window Controls
maximize-screen- OS maximize (bordered, taskbar visible)fullscreen-screen- Fullscreen mode (platform-specific behavior)minimize-screen- Minimize window to taskbar/dock
β‘ Performance Characteristics
Windows Performance
- Total time: 15-60ms per operation
- Detection: 2-5ms (direct Win32 API)
- Manipulation: 10-47ms (SetWindowPos with corrections)
- Best case: 15-25ms for simple splits
- Typical case: 20-35ms for most operations
macOS Performance
- Total time: 50-150ms per operation
- Detection: 20-50ms (AppleScript + Accessibility API)
- Manipulation: 15-55ms (AXUIElement operations)
- Best case: 50-80ms for simple splits
- Typical case: 80-120ms for most operations
π Technical Architecture
Windows Implementation
- Direct Win32 API calls via
pywin32 - DWM integration for accurate frame bounds
- DPI-aware positioning for high-resolution displays
- Two-pass positioning for precise window placement
macOS Implementation
- AppleScript focus detection for reliability
- Accessibility API for window manipulation
- Fallback mechanisms for edge cases
- Screen-aware positioning respecting menu bar and Dock
Cross-Platform Features
- Automatic platform detection
- Conditional dependency loading
- Unified API interface
- Error handling and recovery
π Platform Dependencies
Windows
- Required:
pywin32>=306 - Purpose: Win32 API access, DWM integration, window manipulation
macOS
- Required:
pyobjc-core>=10.1,<11,pyobjc-framework-Cocoa>=10.1,<11,pyobjc-framework-Quartz>=10.1,<11,pyobjc-framework-ApplicationServices>=10.1,<11 - Purpose: Accessibility API, AppleScript integration, window management
π¨ Troubleshooting
Common Issues
macOS Focus Detection Problems
- Symptom: Windows don't move or wrong windows are selected
- Solution: Ensure Terminal has Accessibility permissions in System Preferences > Security & Privacy > Privacy > Accessibility
Windows DPI Issues
- Symptom: Windows positioned incorrectly on high-DPI displays
- Solution: The server automatically handles DPI awareness, but ensure
pywin32>=306is installed
MCP Client Connection Issues
- Symptom: Functions work when called directly but fail via MCP
- Solution: Check MCP client logs, ensure proper configuration, restart MCP client
Performance Optimization
- First run: May be slower due to system warm-up
- Subsequent runs: Should be consistently fast
- Complex apps: Safari, Chrome may take longer due to window structure
π§ Development
Project Structure
computer-split-screen/
βββ src/splitscreen_mcp/
β βββ __init__.py # Package initialization
β βββ __main__.py # MCP server entry point
β βββ window_actions.py # Core window management logic
βββ pyproject.toml # Project configuration
βββ README.md # This file
βββ LICENSE # MIT License
Building from Source
git clone https://github.com/Beta0415/computer-split-screen-mcp.git
cd computer-split-screen-mcp
uvx install -e .
Running Tests
# Test window detection
python3 -c "from src.splitscreen_mcp.window_actions import left_half_window; left_half_window()"
# Test MCP server
uvx run computer-split-screen-mcp
π License
This project is licensed under the MIT License - see the LICENSE file for details.
π Version History
-
v1.5.0 - Current stable release
- Cross-platform window management
- 16 comprehensive tools
- High-performance implementation
- Full MCP protocol support
-
v1.1.0 - v.1.4.5 - In-progress testing & updates
-
v.1.2.0 - Outdated release
- macOS uses pure AppleScript window relocation method
-
v1.0.0 - Intitial release
Built with β€οΈ for the MCP community
