<!-- manucho-readme-banner:start --> <p align="center"> <img src="assets/readme/banner.svg" alt="MANUMCP project overview" width="100%"> </p> <!-- manucho-readme-banner:end --> <p align="center"> <img src="assets/readme/project-logo.svg" width="240" alt="ManuMCP 3D project logo"> </p>

ManuMCP

<p align="center"> <strong>Conecta un agente MCP con tu ordenador completo.</strong><br> ChatGPT web, Codex, Claude Code, Gemini CLI, Cursor y cualquier cliente compatible pueden trabajar con archivos, aplicaciones y procesos; en Windows y macOS también pueden controlar la interfaz gráfica cuando ManuMCP está ejecutándose localmente. </p> <p align="center"> <a href="https://github.com/ma-nucho-pro/ManuMCP/actions/workflows/ci.yml"><img src="https://github.com/ma-nucho-pro/ManuMCP/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a> <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D22.12-339933.svg" alt="Node.js 22.12 o posterior"></a> <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-stdio%20%7C%20HTTP-7c3aed.svg" alt="Model Context Protocol"></a> <a href="https://m8ven.ai/mcp/ma-nucho-pro-manumcp-1kbdcq"><img src="https://m8ven.ai/badge/mcp/ma-nucho-pro-manumcp-1kbdcq" alt="M8ven Score"></a> </p>

[!IMPORTANT] ManuMCP es un servidor MCP local. No es un bypass de seguridad ni un servicio de administración remota. Ejecuta acciones con los permisos del usuario que inició sesión, y las operaciones que cambian el equipo pasan por una vista previa y una confirmación de un solo uso.

Qué hace

ManuMCP mantiene un agente en tu ordenador y le ofrece a tu cliente de IA herramientas para:

• trabajar en el Escritorio, Descargas o cualquier carpeta accesible de la máquina;
• descubrir y usar otras unidades Windows montadas como pc-d:/, pc-f:/, etc.;
• abrir Word, navegadores, editores y otras aplicaciones;
• consultar y terminar procesos;
• enumerar, enfocar y cerrar ventanas en Windows/macOS;
• leer pantallas, mover el ratón, escribir texto y pulsar combinaciones de teclas en Windows/macOS;
• ejecutar PowerShell/CMD en Windows o sh, bash y zsh en macOS/Linux;
• funcionar sin que Codex permanezca conectado, mientras el agente y el túnel sigan activos.

La idea central es que pc:/ representa el ordenador completo, no solamente una carpeta del proyecto:

| Plataforma | Raíz completa | Otras unidades | | --- | --- | --- | | Windows | pc:/ apunta por defecto a la raíz de la unidad del sistema (C:\) | Cada unidad montada y accesible se descubre como pc-d:/, pc-f:/, etc. | | macOS | pc:/ apunta por defecto a / | Los discos montados aparecen bajo pc:/Volumes/<nombre> | | Linux | pc:/ apunta por defecto a / | Los puntos de montaje están dentro de pc:/ cuando el usuario puede leerlos |

Además existen los alias cómodos workspace:/ y desktop:/ para el Escritorio, y downloads:/ y descargas:/ para Descargas. Una ruta sin alias, como hola mundo.txt, continúa teniendo por defecto el Escritorio para evitar sorpresas.

La capa de archivos mantiene una política no reducible: bloquea credenciales, claves privadas, tokens, archivos .env, almacenes de configuración sensibles, enlaces simbólicos, hard links y carpetas críticas del sistema. El shell confirmado es deliberadamente más potente y puede tocar cualquier recurso que el usuario del proceso pueda tocar; revisa su vista previa.

Cómo funciona

ChatGPT web / Codex / Claude Code / Gemini CLI / Cursor / otro cliente MCP
                         │
             stdio local o túnel MCP seguro
                         ▼
              ManuMCP en tu ordenador
                         │                 │
       archivos y comandos      escritorio gráfico (Windows/macOS)
     pc:/, pc-d:/, workspace:/   ventanas, pantalla, ratón, teclado

<p align="center"> <img src="docs/assets/manumcp-architecture.svg" alt="Diagrama de arquitectura: clientes MCP conectan con el agente local ManuMCP y pasan por confirmación antes de acceder a archivos, comandos o escritorio gráfico" width="100%"> </p>

En Windows, el instalador registra ManuMCP Agent en el Programador de tareas. En macOS instala un LaunchAgent; en Linux intenta instalar un servicio systemd de usuario y, si no está disponible, mantiene un proceso de usuario con reinicio manual. El agente se inicia cuando la sesión del usuario está disponible.

Para que ChatGPT web llegue a ese agente desde fuera de la red local hace falta mantener activo un túnel saliente. ManuMCP incluye helpers para el Secure MCP Tunnel de OpenAI y para stdio; la credencial del túnel es específica de tu cuenta y nunca se inventa ni se publica en este repositorio.

Requisitos

Todos los sistemas

• Node.js 22.12 o posterior y npm.
• Git si vas a clonar el repositorio.
• Un cliente MCP que admita transporte stdio, o un cliente remoto que admita el túnel MCP.
• Una sesión de usuario activa y el ordenador encendido/despierto para el control gráfico.

Windows

• Windows 10 u 11.
• PowerShell 5.1 o PowerShell 7.
• Para ventanas, pantalla, ratón y teclado: una sesión gráfica interactiva. No hace falta ejecutar el instalador como administrador.

macOS

• macOS con Node.js instalado.
• Para controlar ventanas y entrada: concede a la aplicación que ejecuta Node/ManuMCP los permisos de Accessibility.
• Para capture_screen: concede Screen Recording. macOS puede pedir cerrar y volver a abrir la aplicación después del cambio.

Linux

• Linux con Node.js instalado.
• Se admiten archivos, comandos, procesos y apertura de elementos con los permisos del usuario.
• El backend de control gráfico de ventanas, pantallas, ratón, escritura y atajos todavía no está implementado en Linux; esas herramientas devuelven una respuesta de plataforma no compatible.

ChatGPT web

• Acceso de tu cuenta al modo de desarrollador y a apps MCP personalizadas.
• Un túnel Secure MCP de OpenAI creado y asociado al workspace correcto, más el tunnel-client oficial.
• La app MCP debe actualizarse después de cambiar el catálogo de herramientas.

[!NOTE] Instalar ManuMCP en Codex, Claude Code, Gemini CLI o Cursor no instala automáticamente una app dentro de tu cuenta de ChatGPT: son configuraciones distintas. El instalador puede preparar el agente local y los clientes MCP detectados; la parte de ChatGPT web debe completarse en el navegador con la cuenta propietaria y su autorización.

Instalación rápida

Windows

En PowerShell:

git clone https://github.com/ma-nucho-pro/ManuMCP.git
Set-Location ManuMCP
Set-ExecutionPolicy -Scope Process Bypass
.\scripts\install-windows.ps1

El instalador instala las dependencias del lockfile, compila dist, crea el Escritorio y Descargas si hacen falta, genera un token local, guarda las raíces en %APPDATA%\ManuMCP\roots.json y deja el agente respondiendo en http://127.0.0.1:8787/healthz.

Sin parámetros, pc:/ se configura como la raíz de la unidad donde está Windows. Si prefieres una raíz diferente o más estrecha:

.\scripts\install-windows.ps1 -PcRoot "D:\Mis archivos"

Para autorizar explícitamente la unidad del sistema completa:

.\scripts\install-windows.ps1 -PcRoot "C:\"

El valor predeterminado ya cubre C:\ y ManuMCP descubre otras letras de unidad montadas y accesibles. No se crean ni se autorizan letras que no existan.

Instalación desde una terminal sin clonar antes:

& ([scriptblock]::Create((Invoke-WebRequest -UseBasicParsing https://raw.githubusercontent.com/ma-nucho-pro/ManuMCP/main/scripts/bootstrap-windows.ps1).Content))

Para que un agente prepare también los clientes MCP instalados y abra la pantalla de configuración de ChatGPT web:

& ([scriptblock]::Create((Invoke-WebRequest -UseBasicParsing https://raw.githubusercontent.com/ma-nucho-pro/ManuMCP/main/scripts/bootstrap-windows.ps1).Content)) -Clients auto -OpenChatGPT

Si una ruta llamada ManuMCP ya existe y no es un repositorio Git, el bootstrap se detiene y no la sobrescribe. Para máxima trazabilidad, clona el repositorio y ejecuta el instalador visible.

macOS y Linux

En una terminal:

git clone https://github.com/ma-nucho-pro/ManuMCP.git
cd ManuMCP
bash scripts/install-unix.sh

El instalador crea ~/Desktop y ~/Downloads si no existen, usa / como pc:/ por defecto, genera el token local en ~/.config/manumcp/local-token.txt, compila el servidor e instala el arranque del agente:

• macOS: ~/Library/LaunchAgents/com.manumcp.agent.plist;
• Linux con systemd: ~/.config/systemd/user/manumcp.service;
• Linux sin systemd de usuario: proceso de usuario y log en ~/.config/manumcp/logs/.

También puedes usar el bootstrap:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/ma-nucho-pro/ManuMCP/main/scripts/bootstrap-unix.sh)"

Para que el bootstrap configure también los clientes MCP detectados y abra ChatGPT web:

MANUMCP_CLIENTS=auto MANUMCP_OPEN_CHATGPT=1 bash -c "$(curl -fsSL https://raw.githubusercontent.com/ma-nucho-pro/ManuMCP/main/scripts/bootstrap-unix.sh)"

El bootstrap no sobrescribe una carpeta existente que no sea un repositorio Git. Si necesitas una raíz más estrecha:

MANUMCP_PC_ROOT="$HOME" bash scripts/install-unix.sh

Comprueba que el agente quedó activo:

curl -fsS http://127.0.0.1:8787/healthz

La respuesta debe incluir ok: true, pc:/ (raíz completa del equipo) y el transporte http.

Instalación completa guiada por una IA

El flujo recomendado para Codex, Claude Code, Gemini CLI, Cursor u otro agente con terminal es:

1. Leer este README completo y detectar el sistema operativo, el cliente MCP instalado y si el cliente tiene navegador/computer-use.
2. Ejecutar el bootstrap del sistema operativo. El bootstrap instala dependencias del proyecto, compila dist, crea el arranque del agente, comprueba /healthz y ejecuta configure-clients.mjs --client auto.
3. Si el cliente no estaba instalado, conservar el comando stdio y mostrarlo como configuración pendiente; no inventar una instalación ni reemplazar otro cliente.
4. Si el cliente ya tenía una entrada llamada manumcp, dejarla intacta o usar --replace solo cuando el usuario pidió actualizarla. Cursor conserva los demás servidores y crea un respaldo antes de modificar su JSON.
5. Si el agente tiene navegador/computer-use, abrir https://chatgpt.com/#settings/Apps, comprobar que la cuenta y el workspace son los del propietario, y completar el flujo de Developer mode: crear o actualizar la app, seleccionar el túnel de ManuMCP, usar Scan Tools y guardar. Si la app ya existe, pulsar Actualizar/Refresh para redescubrir el catálogo.
6. Si ChatGPT solicita inicio de sesión, una clave, autorización de cuenta/workspace o permisos del sistema, detenerse exactamente en ese paso para que el propietario lo haga. El agente nunca debe pedir, copiar, registrar ni subir contraseñas, cookies o claves privadas.
7. Verificar por separado el cliente local con tools/list y ChatGPT web con get_device_health, list_storage_volumes y una lectura pequeña de pc:/. No declarar la instalación completa si una de esas comprobaciones falla.

El comando unificado, después de clonar el repositorio, es:

npm run configure-clients -- --client auto --open-chatgpt

Para actualizar únicamente la entrada manumcp de los clientes que ya la tienen:

npm run configure-clients -- --client auto --replace

Para que un agente revise las acciones sin modificar nada:

npm run configure-clients -- --client auto --dry-run

El configurador soporta codex, claude, gemini, cursor, auto y none. Con auto omite los clientes que no están instalados y devuelve un resumen JSON para que el agente sepa qué quedó configurado, qué ya est