AI & Automation#

FoldNotes' CLI (fn) outputs structured JSON, making it a natural bridge between your notes and AI tools. An MCP server and Ollama chat client connect AI models to your FoldNotes knowledge base.

Open source · install from PyPI

The MCP server is published on PyPI as foldnotes-mcp — install it in one command (below). It pairs with the FoldNotes macOS app and its fn CLI, and applies the same licensing and safety limits. The Ollama chat client is open source (see its section below).

Philosophy#

FoldNotes deliberately keeps AI outside the editor. The writing surface is distraction-free — no inline suggestions, no auto-complete, no AI nudges while you think. When you want AI assistance, you reach for it explicitly through external tools.

MCP Server (Model Context Protocol)#

The FoldNotes MCP server wraps the fn CLI as a set of tools that any MCP-compatible client can call — Claude Desktop, Claude Code, or third-party MCP clients.

Available Tools#

Tool	CLI Command	Description
`list_notes`	`fn list`	List and filter notes (by tag, favourites, tasks, dates, archived)
`show_note`	`fn show`	Read a note's content, properties, tasks, or backlinks
`create_note`	`fn create`	Create a new note with content, tags, and properties
`edit_note`	`fn edit`	Append, prepend, replace content; set properties; favourite/archive
`search_notes`	`fn search`	Full-text search with regex, tag filter, titles-only mode
`list_tasks`	`fn tasks`	List tasks (by status, priority, project, due date); each task carries a stable `id`
`add_task`	`fn tasks add`	Add a task to a note; returns the new task's `id`
`complete_task`	`fn tasks complete`	Mark a task as done (by `id` or text)
`cancel_task`	`fn tasks cancel`	Cancel a task (by `id` or text)
`start_task`	`fn tasks progress`	Mark a task as in-progress (by `id` or text)
`reset_task`	`fn tasks reset`	Reset a task to not-started (by `id` or text)
`set_task`	`fn tasks set`	Amend a task's due date, priority, or project (by `id` or text)
`remove_task`	`fn tasks remove`	Delete a task line from a note (by `id` or text)
`list_projects`	`fn tasks projects`	List all projects with task counts
`list_tags`	`fn tags`	List tags with counts, or show notes for a tag
`backlinks`	`fn backlinks`	Find notes referencing a target (with optional context)
`daily_note`	`fn daily`	Show or create a daily note
`daily_append`	`fn daily append`	Append text to a daily note
`delete_note`	`fn delete`	Move a note to the trash (recoverable)
`restore_note`	`fn restore`	Restore a note from the trash
`rename_note`	`fn rename`	Rename a note
`list_properties`	`fn properties list`	List property definitions (the collection schema)
`show_property`	`fn properties show`	Show a property definition's details
`add_property`	`fn properties add`	Create a property definition
`delete_property`	`fn properties delete`	Delete a property definition (values kept)
`property_orphans`	`fn properties orphans`	Find front matter keys with no schema definition
`property_notes`	`fn properties notes`	List notes using a property, optionally by value
`collection_info`	`fn collection info`	Collection stats and cache status
`list_collections`	`fn collections`	List all registered collections
`switch_collection`	`fn collection switch`	Switch the active collection
`open_note`	`fn open`	Open a note in FoldNotes
`archive_note`	`fn archive`	Archive a note (excluded from `list_notes` by default)
`unarchive_note`	`fn unarchive`	Restore an archived note
`list_templates`	`fn templates`	List available note templates
`rename_project`	`fn projects rename`	Rename a project across the collection (tags + task keywords)
`strip_project`	`fn projects strip`	Remove a project's tags and task keywords across the collection
`list_attachments`	`fn attachments list`	List images with size and reference count
`orphan_attachments`	`fn attachments orphans`	List images no note references
`prune_attachments`	`fn attachments prune`	Delete orphaned images (dry-run unless `force`)
`list_queries`	`fn query list`	List saved queries
`run_query`	`fn query run`	Run a saved query; returns matches in the same shape as `list_notes`
`notifications`	`fn notifications`	Notification settings and upcoming task reminders
`version`	—	Show MCP server and fn CLI versions

Task identity

Every task has a stable UUID that survives edits, reordering, and sync. list_tasks returns it as id, and the task tools accept a task_id to act on that exact task — the reliable way to target one task when several share the same wording. Matching by text (a case-insensitive substring, first match) still works when you don't have an id.

Trash is human-owned

The MCP can move a note to the trash (delete_note) and bring it back (restore_note), but it cannot empty the trash or permanently delete a note — that stays a deliberate, human-only action in the app. Task removal (remove_task) edits the note body directly and is not trash-backed, so prefer targeting by task_id.

Working with multiple collections

Every tool takes an optional collection argument (name, UUID, or path) to act on a specific collection for that one call. switch_collection sets a default for later calls — but it changes the CLI's own active collection, which is independent of the app: it never changes which collection the app opens into, so the app always launches where you left it. If a collection you switched to is later removed in the app, the tools notice and revert to your default collection automatically.

Installation#

Prerequisites

The fn CLI — install it from the app: FoldNotes → Install Command Line Tool. The server shells out to fn, so whatever the CLI can do the MCP can do, and the same licensing/safety limits apply.
Python 3.10 or newer.

Install from PyPI — pick one:

# A) uvx — no install, always the latest, nothing to maintain
#    (needs uv: https://docs.astral.sh/uv/)
uvx foldnotes-mcp

# B) pip into an isolated environment — gives a stable `foldnotes-mcp` command
python3 -m venv ~/.foldnotes-mcp
~/.foldnotes-mcp/bin/pip install foldnotes-mcp

Verify it runs — either method starts the server on stdio (press Ctrl-C to stop):

uvx foldnotes-mcp                    # method A, or…
~/.foldnotes-mcp/bin/foldnotes-mcp   # method B

The server auto-discovers fn at /usr/local/bin/fn or /opt/homebrew/bin/fn, falling back to fn on your PATH.

Connect to Claude Desktop#

Open Claude Desktop's config file (create it if it doesn't exist):

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add a foldnotes entry under mcpServers. If you installed with uvx:

{
  "mcpServers": {
    "foldnotes": {
      "command": "uvx",
      "args": ["foldnotes-mcp"]
    }
  }
}

If you used the pip install, point command at the console script (absolute path), with no args:

{
  "mcpServers": {
    "foldnotes": {
      "command": "/Users/you/.foldnotes-mcp/bin/foldnotes-mcp"
    }
  }
}

Restart Claude Desktop. The FoldNotes tools appear under the tools (🔌) menu — try "list my overdue tasks" to confirm it's wired up.

Connect to Claude Code#

Register the server in one command:

# With uvx:
claude mcp add foldnotes -- uvx foldnotes-mcp

# Or with the pip install (absolute path to the console script):
claude mcp add foldnotes -- /Users/you/.foldnotes-mcp/bin/foldnotes-mcp

Add --scope user to make it available in every project, or --scope project to write a shared .mcp.json into a repo.
Confirm it loaded with claude mcp list, or run /mcp inside a Claude Code session.

If the server can't find fn

It looks in /usr/local/bin, then /opt/homebrew/bin, then your PATH. If it comes up empty, re-run FoldNotes → Install Command Line Tool or symlink fn into one of those locations.

Ollama Chat Client#

An interactive chat client connects local Ollama models to your FoldNotes collection. All queries run locally — no data leaves your machine.

Recommended Models#

Model	Size	Speed	Tool Calling
qwen2.5:7b	7B	Fast (~30 tok/s)	Strong (default)
llama3.1:8b	8B	Fast	Good
qwen2.5:14b	14B	Medium	Very strong
qwen2.5:32b	32B	Slower	Excellent (needs 32GB+ RAM)

For tool-calling tasks (structured JSON dispatch), smaller models perform nearly as well as large ones. Use 7B for speed, step up to 14B if you need better reasoning.

Building Your Own Integration#

Any tool that can run shell commands can interact with FoldNotes:

# Every command supports --json for structured output
fn list --json
fn show "Note Title" --body --json
fn tasks --overdue --json
fn search "query" --json

# Write operations
fn create "Title" --content "Body" --tag idea
fn edit "Title" --append "New paragraph"
fn daily append "Quick capture"

# Task management
fn tasks add "Review PR" --note "Sprint Tasks" --due tomorrow --priority high
fn tasks complete "Review PR" --note "Sprint Tasks"

The --json flag on every command ensures reliable parsing. The CLI reads and writes .md files directly — changes are immediately visible to the app via iCloud sync.

See Shortcuts & Automation for Apple Shortcuts, Python, and Raycast examples.