Français · English

mcp-pc — contrôle d'un PC Linux par un assistant (serveur MCP)

Serveur MCP qui permet à un assistant IA compatible de piloter un PC Linux à distance : fichiers et terminal, capture d'écran, souris, clavier, fenêtres, lecture de l'interface des applications en texte (AT-SPI), lancement d'applications et navigation web par une extension de navigateur.

⚠️ Cet outil donne un contrôle complet de la machine (fichiers, shell, écran, clavier, souris) à quiconque s'authentifie. Lisez la section Sécurité avant de l'exposer sur Internet. Projet personnel, non audité.

Architecture

Outils ajoutés : screen_screenshot, screen_click, screen_move, screen_drag, screen_scroll, keyboard_press, keyboard_type, windows_list, windows_control, ui_read, ui_click, ui_set_text, app_list, app_launch, app_profile, app_command, browser_tabs, browser_read, browser_click, browser_type, browser_navigate, browser_extract, browser_tab.

Garde-fou : les commandes qui écrivent sur les disques, partitions ou LVM (mkfs, fdisk, dd of=/dev/…, lvremove, wipefs sans -n…) sont bloquées tant que l'utilisateur n'a pas tapé lui-même sudo touch /etc/mcp-pc-accord-disques (valable 15 minutes ; chemin modifiable avec MCP_ACCORD_FILE). C'est une protection heuristique, pas une frontière de sécurité.

Related MCP server: mcp-linux-desktop

Prérequis

Développé et utilisé sous Linux avec KDE Plasma (Wayland) ; d'autres environnements ne sont pas pris en charge (KWin, spectacle, qdbus-qt6 et Klipper sont utilisés).

• Node.js 20 ou plus récent, puis npm install dans ce dossier.

• Python 3 avec python-evdev, python-dbus, PyGObject (Atspi) et Pillow.

• Accès en écriture à /dev/uinput pour l'utilisateur (règle udev ou groupe input).

• Un client MCP distant qui gère OAuth, et une URL publique en HTTPS qui redirige vers le port 8788 (tunnel ou reverse proxy de votre choix).

Installation et lancement

npm install
export PUBLIC_URL="https://votre-url-publique"          # URL HTTPS vue par le client
export OAUTH_REDIRECT_URI="https://client.exemple/oauth/callback"   # adresse de retour OAuth de VOTRE client
export SCREEN_WIDTH=1920 SCREEN_HEIGHT=1080              # résolution de l'écran (par défaut 1920x1080)
./start.sh

start.sh attend la session graphique (3 minutes au plus), ce qui permet de le lancer au démarrage comme service utilisateur. Au premier lancement, deux fichiers sont créés (droits 0600) :

• token.txt : la clé secrète à saisir sur la page d'autorisation quand vous connectez votre client ;

• browser-token.txt : le jeton du pont navigateur.

Extension navigateur : dans browser-extension/, copiez config.example.js en config.js, collez-y le contenu de browser-token.txt, puis chargez le dossier comme extension non empaquetée (chrome://extensions, mode développeur).

Variables : PUBLIC_URL et OAUTH_REDIRECT_URI (obligatoires), SCREEN_WIDTH, SCREEN_HEIGHT, BROWSER_BRIDGE_PORT (8790), MCP_ACCORD_FILE.

Sécurité

• Quiconque connaît la clé de token.txt et atteint votre URL peut contrôler la machine avec les droits de l'utilisateur. Gardez cette clé longue et secrète ; ne la partagez jamais.

• Ne versionnez jamais token.txt, browser-token.txt, oauth-state.json ni browser-extension/config.js (le .gitignore les exclut). oauth-state.json contient les jetons d'accès : le supprimer révoque toutes les connexions.

• Exposez le service sur Internet seulement derrière un tunnel ou un reverse proxy que vous maîtrisez, de préférence avec un contrôle d'accès supplémentaire. Les jetons d'accès durent 30 jours, les jetons de renouvellement 365 jours.

• Si vous n'avez pas besoin d'un accès distant, gardez tout sur 127.0.0.1.

• sudo : le serveur n'élève jamais ses droits de lui-même ; les instructions données à l'assistant exigent votre accord avant toute commande root, mais ce n'est qu'une consigne, pas un verrou technique.

Licence

GPL-3.0. Dépendances : Desktop Commander et supergateway (MIT).

English

mcp-pc — control a Linux PC from an AI assistant (MCP server)

An MCP server that lets a compatible AI assistant drive a Linux PC remotely: files and terminal, screenshots, mouse, keyboard, windows, text-based reading of application interfaces (AT-SPI), launching applications, and web browsing through a browser extension.

⚠️ This tool gives complete control of the machine (files, shell, screen, keyboard, mouse) to anyone who authenticates. Read the Security section before exposing it to the Internet. Personal project, not audited.

Architecture

Added tools: screen_screenshot, screen_click, screen_move, screen_drag, screen_scroll, keyboard_press, keyboard_type, windows_list, windows_control, ui_read, ui_click, ui_set_text, app_list, app_launch, app_profile, app_command, browser_tabs, browser_read, browser_click, browser_type, browser_navigate, browser_extract, browser_tab.

Safeguard: commands that write to disks, partitions or LVM (mkfs, fdisk, dd of=/dev/…, lvremove, wipefs without -n…) are blocked until the user types sudo touch /etc/mcp-pc-accord-disques themselves (valid for 15 minutes; path changeable with MCP_ACCORD_FILE). This is a heuristic protection, not a security boundary.

Requirements

Developed and used on Linux with KDE Plasma (Wayland); other environments are not supported (KWin, spectacle, qdbus-qt6 and Klipper are used).

• Node.js 20 or newer, then npm install in this folder.

• Python 3 with python-evdev, python-dbus, PyGObject (Atspi) and Pillow.

• Write access to /dev/uinput for the user (udev rule or input group).

• A remote MCP client that supports OAuth, and a public HTTPS URL forwarding to port 8788 (tunnel or reverse proxy of your choice).

Installation and start

npm install
export PUBLIC_URL="https://your-public-url"                      # HTTPS URL as seen by the client
export OAUTH_REDIRECT_URI="https://client.example/oauth/callback"   # OAuth callback of YOUR client
export SCREEN_WIDTH=1920 SCREEN_HEIGHT=1080                      # screen resolution (default 1920x1080)
./start.sh

start.sh waits for the graphical session (3 minutes at most), so it can be started at boot as a user service. On first run, two files are created (mode 0600):

• token.txt: the secret key to type on the authorization page when you connect your client;

• browser-token.txt: the browser bridge token.

Browser extension: in browser-extension/, copy config.example.js to config.js, paste the content of browser-token.txt into it, then load the folder as an unpacked extension (chrome://extensions, developer mode).

Variables: PUBLIC_URL and OAUTH_REDIRECT_URI (required), SCREEN_WIDTH, SCREEN_HEIGHT, BROWSER_BRIDGE_PORT (8790), MCP_ACCORD_FILE.

Security

• Anyone who knows the key in token.txt and can reach your URL can control the machine with the user's rights. Keep that key long and secret; never share it.

• Never commit token.txt, browser-token.txt, oauth-state.json or browser-extension/config.js (the .gitignore excludes them). oauth-state.json holds the access tokens: deleting it revokes every connection.

• Expose the service to the Internet only behind a tunnel or reverse proxy you control, preferably with an extra access control. Access tokens last 30 days, refresh tokens 365 days.

• If you do not need remote access, keep everything on 127.0.0.1.

• sudo: the server never elevates by itself; the instructions given to the assistant require your approval before any root command, but that is only an instruction, not a technical lock.

License

GPL-3.0. Dependencies: Desktop Commander and supergateway (MIT).