Installing Fouine and its MCP server

This page is written for an AI assistant that has been asked to "install the Fouine MCP", and for the person driving it. It says where things are, gives the commands verbatim, and says how to check the result. Everything runs on the Mac; nothing needs an administrator password.

The short version. Fouine is a macOS application that indexes the documents in the folders you choose (PDF, EPUB, DOCX, scans, notes, audio…) and searches them page by page. It ships a read-only MCP server, speaking JSON-RPC over standard input and output, that lets an assistant search that index and read a page. One command configures the usual clients:

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

1. Is Fouine installed?

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

If both answer, go to step 3. The fouine command line lives inside the application, at /Applications/Fouine.app/Contents/Helpers/fouine. It is on the PATH as plain fouine only once the person has used Fouine ▸ Settings ▸ Advanced ▸ "Install the command-line tool…", which links it from /usr/local/bin. The full path always works; the rest of this page uses it.

2. Installing the application

Fouine is distributed as a disk image, signed and notarised by Apple, from the releases page: github.com/basedpolymer/fouine/releases/latest. It includes a 30-day trial with everything switched on; a licence key (€39, once) is pasted later into Settings ▸ Licence. By hand: open the .dmg, drag Fouine.app onto Applications. From a 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

Leave the application in /Applications: macOS files its privacy permissions by path and signature, and an application that moves asks for them again.

The index is built by the person, not by the assistant. Fouine indexes nothing until a folder has been added: Fouine ▸ "Add a folder…", or a folder dropped into the window. macOS then asks for permission to read that folder; only the person can answer. The command line can do the same from a terminal, fouine root add ~/Documents/Thesis then fouine index, but the application keeps the index up to date in the background and is the normal way.

3. Configuring the assistant's client

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

The command inspects the Mac and configures every client it finds, keeping the other servers and settings of each file:

Client	What is written
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json`, entry `fouine` in `mcpServers`
Claude Code	`claude mcp add --scope user fouine -- <path> mcp --stdio`, if `claude` is on the `PATH`
Cursor	`~/.cursor/mcp.json`
Codex (CLI, app, VS Code extension)	table `[mcp_servers.fouine]` in `~/.codex/config.toml`
Antigravity (2.0, IDE, CLI)	`~/.gemini/config/mcp_config.json`

A client whose folder does not exist is reported as skipped ("Codex is not installed"). Useful options: --client codex (or claude-desktop, claude-code, cursor, antigravity) for one client only; --dry-run to see what would be written without writing; --json for a machine-readable report; --folders Thesis,Courses so that the server only ever serves those folders (by the label shown in the sidebar). Then restart the client: it starts the server itself.

4. Any other client

Nothing in Fouine is specific to the five clients above: any client that speaks MCP over standard input and output can run the server. Ask Fouine for the entry to copy, resolved for this Mac:

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

It writes nothing and prints the command line, an mcpServers-style JSON entry and a TOML table. The two shapes, with the standard path:

{
  "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"]

Known places, as of September 2026: Gemini CLI reads mcpServers in ~/.gemini/settings.json; Windsurf in ~/.codeium/windsurf/mcp_config.json; VS Code reads a servers object in its mcp.json (command "MCP: Add Server"), with "type": "stdio" next to command and args. --print --json gives {"command": …, "args": […]} alone, for a script. A client with no MCP support at all can still use the command line, which returns the same data: fouine search "nitric acid" --json, fouine read <doc_id> <page>, fouine list --json, fouine status --json.

5. Checking that it works

The server must answer one line of JSON to an initialize request:

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

From the client, call the fouine_status tool: it says how many documents and pages are indexed and whether search by meaning is available. fouine status --json says the same from a terminal. Claude Desktop keeps the server's log in ~/Library/Logs/Claude/mcp-server-fouine.log; the server itself writes to standard error only, FOUINE_MCP_LOG=debug for more.

6. What the server offers, and what it refuses

Five read-only tools: fouine_status, fouine_search (full-text, fuzzy and by meaning, with filters), fouine_read_page (the text Fouine extracted or recognised on one page, with context pages), fouine_similar_pages and fouine_list_documents. Every result names the document and the page, and carries a fouine:// link that reopens the document at that page in the application.

The server never writes to the index, never starts an indexing pass, and never returns the original files, only the text of the pages the assistant asked for. Nothing leaves the Mac except what the assistant's own client sends to its model. --folders restricts what a given server can see; a .fouineignore file at the top of a folder keeps files out of the index altogether. When the trial ends, searching and the server keep working; only updating the index stops.

7. If something is wrong

"command not found: fouine": use the full path, /Applications/Fouine.app/Contents/Helpers/fouine.
The server does not appear in the client: restart the client; with claude mcp add, check that the -- is there; run the initialize line above.
"no Fouine index at …": nothing has been indexed yet. The person adds a folder in the application.
"this Fouine index was written by a newer version": the client runs an old copy of the binary. Point it at the copy inside the application, or run fouine mcp install again.
Search by meaning unavailable: the optional 220 MB model is not installed; Fouine ▸ Settings, or fouine model download. Full-text search works without it.

The complete reference of the server, its tools and its protocol: docs/mcp.md; of the command line: docs/cli.md. What Fouine sends, to whom, and when: the privacy page.