mcp-human-mouse
Provides mouse control on Linux under X11 or XWayland via pynput, enabling realistic cursor movement, clicks, drags, scrolling, and trace capture.
Provides mouse control on macOS via CoreGraphics/Quartz, enabling realistic cursor movement, clicks, drags, scrolling, trace capture, and Accessibility permission handling.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mcp-human-mouse
Servidor MCP (Model Context Protocol) que permite a un agente leer la posición del ratón y moverlo, hacer clic, arrastrar y desplazar la rueda con trayectorias que imitan el movimiento de una persona.
No hace saltos instantáneos ni líneas rectas a velocidad constante: genera curvas con aceleración y frenada suaves, temblor de baja amplitud, sobrepaso y corrección final, pausas de reacción y tiempos de presión variables.
move_human(x=1200, y=700, style="natural")
Herramientas
Herramienta | Qué hace |
| Posición actual, botones pulsados, área de pantalla y monitores. |
| Mueve el cursor a |
| Clic, doble clic o triple clic, con aproximación humana y timing realista. |
| Arrastra manteniendo pulsado el botón; suelta siempre, incluso si se cancela. |
| Rueda en bloques irregulares de 1-5 líneas con pausas. |
| Graba posición y botones durante N segundos y devuelve muestras y estadísticas. |
| Pide permiso de Accesibilidad al sistema (macOS). |
| Cancela el movimiento en curso en el siguiente paso. |
| Backend, pantallas, posición, permiso y límites. Llámala primero. |
Estilos
Estilo | Uso | Rasgos |
| Por defecto | ~0,2-1,5 s según distancia, temblor normal, sobrepaso frecuente. |
| Movimientos rápidos | Más corto, algo más de sobrepaso y temblor. |
| Objetivos pequeños | Más lento, poco temblor, sin sobrepaso. |
| Demostraciones | El más lento y pausado. |
Parámetros útiles
duration_s: fija la duración; si se omite se calcula con la ley de Fitts.jitter: multiplicador del temblor (0= sin temblor).curvature: multiplicador de la curvatura (0= recto).overshoot:truefuerza sobrepaso,falselo desactiva,nulldecide solo.clamp: si el destino está fuera de pantalla, lo ajusta al borde en vez de fallar.dry_run: simula y devuelve la trayectoria sin publicar eventos.
Related MCP server: Open Computer Use
Instalación
Requisitos: Python 3.10-3.12 y, en macOS, permiso de Accesibilidad.
git clone https://github.com/cobraneeo/mcp-human-mouse.git
cd mcp-human-mouse
uv sync --python 3.12Sin uv:
python3.12 -m venv .venv
.venv/bin/pip install -e .Prueba que arranca:
.venv/bin/python scripts/smoke_test.pyConfiguración MCP
Cliente genérico (Claude Desktop, Cursor, etc.)
Sustituye /ABS/mcp-human-mouse por la ruta real:
{
"mcpServers": {
"human-mouse": {
"command": "/ABS/mcp-human-mouse/.venv/bin/python",
"args": ["/ABS/mcp-human-mouse/server.py"]
}
}
}En Claude Desktop para macOS el archivo es
~/Library/Application Support/Claude/claude_desktop_config.json.
DeepSeek Harness
Añade esta entrada a cordis.patch.yml del perfil activo:
- id: mcp-manager
config:
servers:
human-mouse:
transport: stdio
command: /ABS/mcp-human-mouse/.venv/bin/python
args: ["/ABS/mcp-human-mouse/server.py"]
enabled: true
startupTimeoutMs: 30000El archivo del perfil desktop está en:
~/Library/Application Support/IDE .NET/harness-home/profiles/desktop/cordis.patch.ymlEl parche del perfil reemplaza el mapa
serverscompleto. Si ya tienes otros servidores MCP configurados ahí, añádelos junto ahuman-mouse.
Reinicia DeepSeek Harness (o recarga el perfil) y comprueba que aparecen las
herramientas mcp__human-mouse__*.
Permisos en macOS
Leer la posición no requiere permiso. Publicar eventos de ratón sí: sin Accesibilidad, el servidor puede calcular la trayectoria pero el cursor no se mueve.
Llama a
diagnosticsy miraaccessibility.trusted.Si es
false, llama arequest_permissionpara que aparezca el diálogo; si no aparece, abre Ajustes del Sistema → Privacidad y seguridad → Accesibilidad.Activa la aplicación que lanza el servidor MCP:
DeepSeek Harness: IDE .NET.
Claude Desktop: Claude.
Uso manual: Terminal (o iTerm).
Reinicia esa aplicación (y el servidor MCP).
El proceso hijo hereda el permiso del proceso responsable, así que hay que activar la app host, no el binario de Python.
En Windows no hace falta permiso especial; en Linux se necesita una sesión X11 o XWayland.
Ejemplos de uso
Llama a diagnostics y dime si puedes mover el ratón.
Mueve el cursor al botón de guardar (742, 512) con estilo precise y luego
haz clic.
Haz doble clic en (320, 240) con el botón izquierdo.
Arrastra desde (400, 300) hasta (900, 650) en 1,2 segundos.
Baja 12 líneas con la rueda sobre el centro de la ventana.
Graba 3 segundos de mi movimiento del ratón y dime la velocidad máxima.
Simula un movimiento a (1400, 800) sin moverlo (dry_run) y enséñame la
duración y los pasos.Variables de entorno
Variable | Por defecto | Efecto |
|
|
|
|
|
|
| aleatorio | Fija la semilla para trayectorias reproducibles. |
|
| Límite de duración en segundos. |
|
|
|
Cómo se genera el movimiento
Duración: ley de Fitts (
0,12 + 0,11·log2(D/8+1)), con variación aleatoria y multiplicador de estilo.Curva: Bézier cúbica con desplazamiento perpendicular aleatorio; la trayectoria se curva ligeramente, nunca es una recta perfecta.
Velocidad: perfil de mínima sacudida
10t³ − 15t⁴ + 6t⁵, que arranca y frena con aceleración continua.Temblor: proceso de Ornstein-Uhlenbeck (ruido correlacionado, no blanco) más un tremor senoidal de 7,5-11,5 Hz y 0,3 px.
Sobrepaso: en distancias largas apunta 3-22 px más allá y corrige con un submovimiento corto tras una micro-pausa.
Asentamiento: 1-2 pasos de menos de 1 px al final, con pausa variable.
Eventos: 100-144 Hz; el último punto es exactamente el destino.
El generador es Python puro y se prueba sin mover el ratón.
Seguridad y límites
Mueve el ratón de verdad. Prueba primero con
dry_run=true.stop_motiones cooperativo: se aplica en el siguiente paso de la trayectoria (milisegundos). Si algo va mal, mueve el ratón a mano o mata el servidor conCtrl+C.Límites: 30 s por movimiento, 3 clics, 60 líneas de rueda, 60 s de captura.
En macOS, los eventos se publican en el HID event tap; algunas apps protegidas (contraseñas, pantallas seguras) los ignoran.
Linux Wayland puro no está soportado; usa X11 o XWayland.
No incluye teclado ni captura de pantalla.
Desarrollo
.venv/bin/python -m pytest # 45 tests
.venv/bin/python scripts/smoke_test.pyEstructura:
human_mouse/
trajectory.py # generador puro (Fitts, Bézier, mínima sacudida, ruido)
engine.py # ejecución, clics, arrastre, rueda, captura, stop
server.py # herramientas MCP (FastMCP)
backends/
macos.py # CoreGraphics / Quartz
windows.py # SendInput
linux.py # pynput (X11)
tests/
scripts/smoke_test.pyLicencia
MIT.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Give your AI hands on every computer you own. Remote control of your Windows, Mac and Linux machines from one ChatGPT, Claude or Cursor chat — even from your phone. Ask it to find out why the office server is crawling, update every PC in the house, sort out your mom's laptop from another city, or ship the site from your work machine while you're on a train. It runs commands, reads files and takes a screenshot when it needs to see the screen. You decide what each computer allows, and you can cut any of them off in a second.
Eyes and hands on real Windows PCs — observe, click, type via Glasswarp API.
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables MCP-capable coding agents to read and drive the user's browser page with a visible, human-like cursor that evades bot detection.15MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to observe and control the user's live desktop by listing apps, reading accessibility trees, and performing clicks, typing, scrolling, dragging, and other input actions with per-action approvals and local audit archives.1MIT
- AlicenseCqualityCmaintenanceEnables agent-native desktop control by driving mouse, keyboard, and interface elements through accessibility-first semantic operations, with fallback to screen coordinates when accessibility cannot reach a target.30MIT
- AlicenseAqualityBmaintenanceLocal Windows x64 MCP server for USB HID mouse control and optional voice dictation. Requires compatible uMouse hardware, firmware and x64 Node.js 22+. MCPB 0.1.1 packages the legacy 0.1.0 stdio runtime; shared-v2 is a separate source development path. The MCPB includes no cloud credentials, defaults speech recognition to disabled, and supports optional local Windows Speech.22409MIT