Installer Fouine et son serveur MCP

Cette page s’adresse à un assistant IA à qui l’on a demandé « installe le MCP de Fouine », et à la personne qui le lui a demandé. Elle donne les emplacements, les commandes exactes et la façon de vérifier le résultat. Tout se passe sur le Mac, et rien ne demande de mot de passe d’administrateur.

En bref. Fouine est une application macOS qui indexe les documents des dossiers que vous choisissez (PDF, EPUB, DOCX, scans, notes, audio…) et y cherche page par page. Elle comprend un serveur MCP en lecture seule (JSON-RPC sur l’entrée et la sortie standard) par lequel un assistant peut chercher dans cet index et lire des pages. Une commande configure les clients courants :

/Applications/Fouine.app/Contents/Helpers/fouine mcp install

1. Fouine est-elle installée ?

ls /Applications/Fouine.app && /Applications/Fouine.app/Contents/Helpers/fouine --version

Si les deux commandes répondent, passez à l’étape 3. La ligne de commande fouine vit dans l’application, à /Applications/Fouine.app/Contents/Helpers/fouine. Elle n’est sur le PATH sous le simple nom fouine qu’une fois que la personne a utilisé Fouine ▸ Réglages ▸ Avancé ▸ « Installer l’outil en ligne de commande… », qui la lie depuis /usr/local/bin. Le chemin complet marche toujours, et cette page l’emploie partout.

2. Installer l’application

Fouine se distribue en image disque, signée et notarisée par Apple, depuis la page des versions : github.com/basedpolymer/fouine/releases/latest. Elle est gratuite. À la main : ouvrez le .dmg et glissez Fouine.app sur Applications. Depuis un terminal :

cd ~/Downloads
curl -L -o Fouine.dmg "$(curl -sL https://api.github.com/repos/basedpolymer/fouine/releases/latest | grep -o 'https://[^"]*\.dmg' | head -1)"
hdiutil attach Fouine.dmg -nobrowse -mountpoint /Volumes/Fouine
ditto /Volumes/Fouine/Fouine.app /Applications/Fouine.app
hdiutil detach /Volumes/Fouine
open /Applications/Fouine.app

Laissez l’application dans /Applications : macOS enregistre les autorisations de confidentialité par chemin et par signature, si bien qu’une application déplacée doit les redemander.

C’est la personne qui construit l’index, pas l’assistant. Fouine n’indexe rien tant qu’aucun dossier n’a été ajouté, par Fouine ▸ « Ajouter un dossier… » ou en déposant un dossier sur la fenêtre. macOS demande alors l’autorisation de lire ce dossier, et seule la personne peut répondre. La ligne de commande sait faire de même (fouine root add ~/Documents/These, puis fouine index), mais on passe d’ordinaire par l’application, qui tient l’index à jour en arrière-plan.

3. Configurer le client de l’assistant

/Applications/Fouine.app/Contents/Helpers/fouine mcp install

La commande cherche les clients installés sur le Mac et configure chacun de ceux qu’elle trouve, sans toucher aux autres serveurs ni aux autres réglages de chaque fichier :

Client	Ce qui est écrit
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json`, entrée `fouine` dans `mcpServers`
Claude Code	`claude mcp add --scope user fouine -- <chemin> mcp --stdio`, si `claude` est sur le `PATH`
Cursor	`~/.cursor/mcp.json`
Codex (CLI, application, extension VS Code)	table `[mcp_servers.fouine]` dans `~/.codex/config.toml`
Antigravity (2.0, IDE, CLI)	`~/.gemini/config/mcp_config.json`

Un client dont le dossier n’existe pas est signalé comme sauté (« Codex is not installed »). Options utiles : --client codex (ou claude-desktop, claude-code, cursor, antigravity) pour un seul client ; --dry-run pour voir ce qui serait écrit sans rien écrire ; --json pour un rapport lisible par une machine ; --folders These,Cours pour limiter le serveur à ces dossiers, nommés comme dans la barre latérale. Puis relancez le client : c’est lui qui démarre le serveur.

4. Tout autre client

Rien dans Fouine n’est propre aux cinq clients ci-dessus : tout client qui parle MCP sur l’entrée et la sortie standard peut lancer le serveur. Fouine affiche l’entrée à copier, avec les chemins de ce Mac :

/Applications/Fouine.app/Contents/Helpers/fouine mcp install --print

Elle n’écrit rien. Elle affiche la ligne de commande, une entrée JSON au format mcpServers et une table TOML. Voici les deux, avec le chemin standard :

{
  "mcpServers": {
    "fouine": {
      "command": "/Applications/Fouine.app/Contents/Helpers/fouine",
      "args": ["mcp", "--stdio"]
    }
  }
}

[mcp_servers.fouine]
command = "/Applications/Fouine.app/Contents/Helpers/fouine"
args = ["mcp", "--stdio"]

Où regardent d’autres clients, en septembre 2026 : Gemini CLI lit mcpServers dans ~/.gemini/settings.json ; Windsurf, dans ~/.codeium/windsurf/mcp_config.json ; VS Code lit un objet servers dans son mcp.json (commande « MCP: Add Server »), avec "type": "stdio" à côté de command et args. --print --json donne {"command": …, "args": […]} seul, pour un script. Un client qui ne connaît pas MCP peut toujours passer par la ligne de commande, qui rend les mêmes données : fouine search "acide nitrique" --json, fouine read <doc_id> <page>, fouine list --json, fouine status --json.

5. Vérifier que ça marche

Le serveur doit répondre à une requête initialize par une ligne de JSON :

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{}}}' \
  | /Applications/Fouine.app/Contents/Helpers/fouine mcp --stdio

Depuis le client, appelez l’outil fouine_status : il indique combien de documents et de pages sont indexés, et si l’index est à jour. fouine status --json donne la même chose depuis un terminal. Claude Desktop garde le journal du serveur dans ~/Library/Logs/Claude/mcp-server-fouine.log ; le serveur lui-même n’écrit que sur la sortie d’erreur (FOUINE_MCP_LOG=debug pour plus de détails).

6. Ce que le serveur offre, et ce qu’il refuse

Quatre outils en lecture seule : fouine_status, fouine_search (plein texte et flou, avec filtres), fouine_read_page (le texte que Fouine a extrait ou reconnu sur une page, avec les pages voisines) et fouine_list_documents. Chaque résultat nomme le document et la page, et porte un lien fouine:// qui rouvre le document à cette page dans l’application.

Le serveur n’écrit jamais dans l’index, ne lance jamais d’indexation et ne rend jamais les fichiers d’origine, seulement le texte des pages que l’assistant demande. Rien ne quitte le Mac, sauf ce que le client de l’assistant envoie lui-même à son modèle. --folders limite ce qu’un serveur donné peut voir ; un fichier .fouineignore à la racine d’un dossier tient des fichiers entièrement hors de l’index.

7. Si quelque chose cloche

« command not found: fouine » : employez le chemin complet, /Applications/Fouine.app/Contents/Helpers/fouine.
Le serveur n’apparaît pas dans le client : relancez le client. Avec claude mcp add, vérifiez que le -- est bien là. Lancez la ligne initialize ci-dessus.
« no Fouine index at … » : rien n’a encore été indexé. La personne doit ajouter un dossier dans l’application.
« this Fouine index was written by a newer version » : le client lance une ancienne copie du binaire. Pointez-le vers la copie dans l’application, ou relancez fouine mcp install.

La référence complète du serveur, de ses outils et de son protocole (en anglais) : docs/mcp.md ; de la ligne de commande : docs/cli.md. Ce que Fouine envoie, à qui et quand : la page Vie privée.