Installer Fouine et son serveur MCP

Cette page est écrite pour un assistant IA à qui l’on a demandé « installe le MCP de Fouine », et pour la personne qui le pilote. Elle dit où sont les choses, donne les commandes telles quelles, et dit comment vérifier le résultat. Tout se passe sur le Mac ; 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 les cherche page par page. Elle embarque un serveur MCP en lecture seule, qui parle JSON-RPC sur l’entrée et la sortie standard, et qui laisse un assistant chercher dans cet index et lire une page. 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 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 ; la suite de cette page l’emploie.

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 comprend un essai de 30 jours avec tout d’activé ; la clé de licence (39 €, une fois) se colle plus tard dans Réglages ▸ Licence. À la main : ouvrir le .dmg, glisser 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 range ses autorisations de confidentialité par chemin et par signature, et une application qui bouge les redemande.

L’index se construit par la personne, pas par l’assistant. Fouine n’indexe rien tant qu’un dossier n’a pas été ajouté : Fouine ▸ « Ajouter un dossier… », ou un dossier déposé dans la fenêtre. macOS demande alors l’autorisation de lire ce dossier ; seule la personne peut répondre. La ligne de commande sait faire la même chose depuis un terminal, fouine root add ~/Documents/These puis fouine index, mais l’application tient l’index à jour en arrière-plan et reste la voie normale.

3. Configurer le client de l’assistant

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

La commande inspecte le Mac et configure chaque client qu’elle trouve, en conservant les autres serveurs et 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 écrire ; --json pour un rapport lisible par machine ; --folders These,Cours pour que le serveur ne serve jamais que ces dossiers (par l’étiquette affichée 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. Demandez à Fouine l’entrée à copier, résolue pour ce Mac :

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

Elle n’écrit rien et imprime la ligne de commande, une entrée JSON de forme mcpServers et une table TOML. Les deux formes, 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"]

Emplacements connus, 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 sans aucune prise en charge du MCP peut encore 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 ligne de JSON à une requête initialize :

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 dit combien de documents et de pages sont indexés et si la recherche par le sens est disponible. fouine status --json dit 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 en avoir plus.

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

Cinq outils en lecture seule : fouine_status, fouine_search (plein texte, flou et par le sens, avec filtres), fouine_read_page (le texte que Fouine a extrait ou reconnu sur une page, avec les pages voisines), fouine_similar_pages 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 a demandées. Rien ne quitte le Mac, sauf ce que le client de l’assistant envoie lui-même à son modèle. --folders restreint ce qu’un serveur donné peut voir ; un fichier .fouineignore à la racine d’un dossier tient des fichiers hors de l’index tout court. À la fin de l’essai, la recherche et le serveur continuent de fonctionner ; seule la mise à jour de l’index s’arrête.

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 là ; lancez la ligne initialize ci-dessus.
« no Fouine index at … » : rien n’a encore été indexé. La personne ajoute un dossier dans l’application.
« this Fouine index was written by a newer version » : le client lance une vieille copie du binaire. Pointez-le vers la copie dans l’application, ou relancez fouine mcp install.
Recherche par le sens indisponible : le modèle optionnel de 220 Mo n’est pas installé ; Fouine ▸ Réglages, ou fouine model download. La recherche plein texte marche sans lui.

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