mcp-screen-operation
Advanced tools
A modern Model Context Protocol (MCP) server for cross-platform screen and window operations, built with FastMCP and supporting multiple transport protocols.
The server uses a clean, platform-agnostic architecture:
WindowManager interface with platform-specific implementationsOnce published to PyPI, you can install and run easily:
# Install with uv (recommended)
uvx mcp-screen-operation # Run directly without installation
# Or install with pip
pip install mcp-screen-operation
Create and activate a virtual environment:
python -m venv venv
# On Windows
.\venv\Scripts\Activate.ps1
# On Linux/macOS
source venv/bin/activate
Install the project in editable mode with platform-specific dependencies:
pip install -e "."
Install with development tools included:
pip install -e ".[dev]"
Core dependencies (automatically installed):
fastmcp>=2.3.0 - Modern MCP server frameworkmcp>=1.9.4 - Model Context Protocol librarymss - Cross-platform screenshot libraryPillow - Image processingpyautogui - Cross-platform automation libraryPlatform-specific dependencies:
python-xlib - X11 window managementpywin32 - Windows API accesspyobjc-framework-Quartz, pyobjc-framework-Cocoa - macOS window managementDevelopment dependencies (installed with [dev]):
pylint - Code lintingpylint-plugin-utils - Pylint utilitiespylint-mcp - MCP-specific linting rulesblack - Code formatting# Clone and install for your platform
git clone <repository-url>
cd mcp-screen-operation
python -m venv venv
.\venv\Scripts\Activate.ps1 # Windows
pip install -e "."
# Clone and setup development environment
git clone <repository-url>
cd mcp-screen-operation
python -m venv venv
.\venv\Scripts\Activate.ps1 # Windows
pip install -e ".[dev]"
# Run development tools
black src/
pylint src/
mcp-screen-operation --help
usage: mcp-screen-operation [-h] [--transport {stdio,sse,streamable-http}]
[--port PORT] [--host HOST]
MCP Screen Operation Server
options:
-h, --help show this help message and exit
--transport {stdio,sse,streamable-http}
Transport protocol to use (default: stdio)
--port PORT Port for HTTP-based transports (default: 8205)
--host HOST Host for HTTP-based transports (default: 127.0.0.1)
# Check version
mcp-screen-operation --version
Perfect for local tools and Claude Desktop integration:
mcp-screen-operation
# or explicitly
mcp-screen-operation --transport stdio
Modern HTTP-based protocol for web deployments:
mcp-screen-operation --transport streamable-http --port 8205
Access at: http://localhost:8205/mcp
Server-Sent Events for legacy web deployments:
mcp-screen-operation --transport sse --port 8205
Access at: http://localhost:8205/sse
Use FastMCP's development mode with inspector:
fastmcp dev src/screen_operation_server/main.py
You can use the MCP Inspector to test and debug your MCP server interactively:
# Install and run MCP Inspector
npx @modelcontextprotocol/inspector
The MCP Inspector provides a web-based interface to:
get_screen_info(): Retrieves information about connected displays
capture_screen_by_number(monitor_number: int): Captures a screenshot of the specified monitor
monitor_number - The monitor to capture (0-based index)capture_all_screens(): Captures all connected monitors and stitches them into a single image
get_window_list(): Retrieves a list of currently open windows
capture_window(window_id: int): Captures a screenshot of the specified window
window_id - The window ID to capturemouse_move(x: int, y: int, duration: float = 0.0): Moves the mouse cursor
x, y - Target coordinates; duration - Movement duration in secondsmouse_click(x: int, y: int, button: str = "left", clicks: int = 1): Clicks the mouse
x, y - Click coordinates; button - Mouse button ('left', 'right', 'middle'); clicks - Number of clicksmouse_drag(start_x: int, start_y: int, end_x: int, end_y: int, duration: float = 0.5): Drags the mouse
duration - Drag durationmouse_scroll(clicks: int, x: int = None, y: int = None): Scrolls the mouse wheel
clicks - Scroll amount (positive=up, negative=down); Optional coordinatesget_mouse_position(): Gets current mouse position
keyboard_type(text: str, interval: float = 0.0): Types text
text - Text to type; interval - Delay between keystrokeskeyboard_press(key: str): Presses a single key
key - Key name (e.g., 'enter', 'tab', 'space', 'a')keyboard_hotkey(keys: str): Presses hotkey combination
keys - Keys to press together, separated by '+' (e.g., 'ctrl+c')Add to your Claude Desktop MCP configuration:
{
"mcpServers": {
"screen-operation": {
"command": "mcp-screen-operation",
"args": []
}
}
}
Or after PyPI publication, use uvx for automatic installation:
{
"mcpServers": {
"screen-operation": {
"command": "uvx",
"args": ["mcp-screen-operation"]
}
}
}
For Streamable HTTP:
// Connect to the MCP server
const response = await fetch('http://localhost:8205/mcp', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'tools/call',
params: {
name: 'get_screen_info',
arguments: {}
}
})
});
import asyncio
from fastmcp import FastMCP
async def main():
# Connect to HTTP server
client = FastMCP.create_client('http://localhost:8205/mcp')
# Get screen info
result = await client.call_tool('get_screen_info', {})
print(result)
asyncio.run(main())
The server automatically checks for platform-specific dependencies on startup:
python-xlib availabilitypywin32 availabilityPyObjC availabilityIf dependencies are missing, the server will display installation instructions and exit.
git clone <repository-url>
cd mcp-screen-operation
python -m venv venv
# Activate virtual environment
# Windows:
.\venv\Scripts\Activate.ps1
# Linux/macOS:
source venv/bin/activate
# Install in development mode
pip install -e ".[dev]"
# Format code
black src/
# Run linter
pylint src/
# Test the server
mcp-screen-operation --help
# Test with different transports
mcp-screen-operation --transport stdio
mcp-screen-operation --transport sse --port 8205
mcp-screen-operation --transport streamable-http --port 8205
FAQs
MCP server for screen and window operations.
We found that mcp-screen-operation demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Socket’s new Tier 1 Reachability filters out up to 80% of irrelevant CVEs, so security teams can focus on the vulnerabilities that matter.
Research
/Security News
Ongoing npm supply chain attack spreads to DuckDB: multiple packages compromised with the same wallet-drainer malware.
Security News
The MCP Steering Committee has launched the official MCP Registry in preview, a central hub for discovering and publishing MCP servers.