Installing Fouine and its MCP server

This page is for an AI assistant that has been asked to “install the Fouine MCP”, and for the person who asked. It gives the locations, the exact commands, and how to check the result. Everything runs on the Mac, and nothing needs an administrator password.

In short. 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 includes a read-only MCP server (JSON-RPC over standard input and output) through which an assistant can search that index and read pages. 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 commands 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, and this page uses it throughout.

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 is free. By hand: open the .dmg and 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 records privacy permissions by path and signature, so an application that moves has to ask for them again.

The person builds the index, not the assistant. Fouine indexes nothing until a folder has been added, with Fouine ▸ “Add a folder…” or by dropping a folder onto the window. macOS then asks for permission to read that folder, and only the person can answer. The command line can do the same (fouine root add ~/Documents/Thesis, then fouine index), but the application is the usual way, because it keeps the index up to date in the background.

3. Configuring the assistant's client

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

The command looks for the clients installed on the Mac and configures each one it finds, leaving the other servers and settings in each file untouched:

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 to limit the server to those folders, named as in the sidebar. Then restart the client, which 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. Fouine prints the entry to copy, with the paths of this Mac:

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

It writes nothing. It prints the command line, a JSON entry in the mcpServers format, and a TOML table. Here are both, 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"]

Where other clients look, 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 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 should answer an initialize request with one line of 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

From the client, call the fouine_status tool: it reports how many documents and pages are indexed and whether the index is up to date. fouine status --json gives the same from a terminal. Claude Desktop keeps the server's log in ~/Library/Logs/Claude/mcp-server-fouine.log; the server itself logs only to standard error (set FOUINE_MCP_LOG=debug for more).

6. What the server offers, and what it refuses

Four read-only tools: fouine_status, fouine_search (full-text and fuzzy, with filters), fouine_read_page (the text Fouine extracted or recognised on one page, with context 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 indexing, and never returns the original files, only the text of the pages the assistant asks for. Nothing leaves the Mac except what the assistant's own client sends to its model. --folders limits what a given server can see; a .fouineignore file at the top of a folder keeps files out of the index entirely.

7. If something goes 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 needs to add 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.

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