Skip to main content
Glama
mcp-human-mouse

mcp-human-mouse

by cobraneeo

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")

Trayectorias de ejemplo

Herramientas

Herramienta

Qué hace

mouse_state

Posición actual, botones pulsados, área de pantalla y monitores.

move_human

Mueve el cursor a (x, y) con una trayectoria humana.

click_human

Clic, doble clic o triple clic, con aproximación humana y timing realista.

drag_human

Arrastra manteniendo pulsado el botón; suelta siempre, incluso si se cancela.

scroll_human

Rueda en bloques irregulares de 1-5 líneas con pausas.

capture_trace

Graba posición y botones durante N segundos y devuelve muestras y estadísticas.

request_permission

Pide permiso de Accesibilidad al sistema (macOS).

stop_motion

Cancela el movimiento en curso en el siguiente paso.

diagnostics

Backend, pantallas, posición, permiso y límites. Llámala primero.

Estilos

Estilo

Uso

Rasgos

natural

Por defecto

~0,2-1,5 s según distancia, temblor normal, sobrepaso frecuente.

fast

Movimientos rápidos

Más corto, algo más de sobrepaso y temblor.

precise

Objetivos pequeños

Más lento, poco temblor, sin sobrepaso.

slow

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: true fuerza sobrepaso, false lo desactiva, null decide 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.12

Sin uv:

python3.12 -m venv .venv
.venv/bin/pip install -e .

Prueba que arranca:

.venv/bin/python scripts/smoke_test.py

Configuració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: 30000

El archivo del perfil desktop está en:

~/Library/Application Support/IDE .NET/harness-home/profiles/desktop/cordis.patch.yml

El parche del perfil reemplaza el mapa servers completo. Si ya tienes otros servidores MCP configurados ahí, añádelos junto a human-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.

  1. Llama a diagnostics y mira accessibility.trusted.

  2. Si es false, llama a request_permission para que aparezca el diálogo; si no aparece, abre Ajustes del Sistema → Privacidad y seguridad → Accesibilidad.

  3. Activa la aplicación que lanza el servidor MCP:

    • DeepSeek Harness: IDE .NET.

    • Claude Desktop: Claude.

    • Uso manual: Terminal (o iTerm).

  4. 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

HUMAN_MOUSE_DRY_RUN

0

1 hace que todas las herramientas simulen.

HUMAN_MOUSE_SPEED

1.0

>1 más lento, <1 más rápido.

HUMAN_MOUSE_SEED

aleatorio

Fija la semilla para trayectorias reproducibles.

HUMAN_MOUSE_MAX_DURATION

30

Límite de duración en segundos.

HUMAN_MOUSE_ALLOW_UNTRUSTED

0

1 permite publicar aunque el SO diga que no hay permiso (útil para diagnosticar).

Cómo se genera el movimiento

  1. Duración: ley de Fitts (0,12 + 0,11·log2(D/8+1)), con variación aleatoria y multiplicador de estilo.

  2. Curva: Bézier cúbica con desplazamiento perpendicular aleatorio; la trayectoria se curva ligeramente, nunca es una recta perfecta.

  3. Velocidad: perfil de mínima sacudida 10t³ − 15t⁴ + 6t⁵, que arranca y frena con aceleración continua.

  4. Temblor: proceso de Ornstein-Uhlenbeck (ruido correlacionado, no blanco) más un tremor senoidal de 7,5-11,5 Hz y 0,3 px.

  5. Sobrepaso: en distancias largas apunta 3-22 px más allá y corrige con un submovimiento corto tras una micro-pausa.

  6. Asentamiento: 1-2 pasos de menos de 1 px al final, con pausa variable.

  7. 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_motion es 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 con Ctrl+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.py

Estructura:

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.py

Licencia

MIT.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      1
      MIT
    • A
      license
      C
      quality
      C
      maintenance
      Enables 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.
      30
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Local 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.
      22
      409
      MIT