@cardmagic/notes

CLI and MCP server to search and browse Apple Notes with fuzzy matching.

Features

• Fuzzy search - Find notes even with typos using MiniSearch
• Full-text search - Searches note titles, snippets, and body content
• Create & delete notes - Manage notes via AppleScript automation
• PDF text extraction - Automatically extracts and indexes text from PDF attachments
• Folder browsing - List and filter notes by folder
• Fast indexing - SQLite FTS5 + MiniSearch for quick searches across thousands of notes
• Dual mode - Use as CLI tool or MCP server for Claude Code integration

Installation

Homebrew

brew install cardmagic/tap/notes

npm

npm install -g @cardmagic/notes

Claude Code Plugin (recommended)

Install as a plugin to get skills (auto-invoked) and slash commands:

# Add the marketplace
claude plugin marketplace add cardmagic/notes

# Install the plugin
claude plugin install notes@cardmagic

This gives you:

• Skill: Claude automatically searches notes when you ask about notes
• Slash commands: /notes:search, /notes:recent, /notes:folders, and more

MCP Server

For direct MCP tool access without the plugin:

claude mcp add --transport stdio notes -- npx -y @cardmagic/notes --mcp

Or install globally first:

npm install -g @cardmagic/notes
claude mcp add --transport stdio notes -- notes --mcp

From source

git clone https://github.com/cardmagic/notes.git
cd notes
make install

# Then add as plugin OR MCP server:
claude plugin marketplace add cardmagic/notes
claude plugin install notes@cardmagic
# OR
claude mcp add --transport stdio notes -- notes --mcp

Requirements

• macOS - Reads from Apple Notes database
• Full Disk Access - Terminal/IDE needs access to ~/Library/Group Containers/
• pdftotext (optional) - For PDF text extraction

# Install pdftotext for PDF support
brew install poppler

Granting Full Disk Access

The tool needs to read your Notes database at ~/Library/Group Containers/group.com.apple.notes/:

1. Open System Settings > Privacy & Security > Full Disk Access
2. Click + and add your terminal app (Terminal.app, iTerm, Warp, etc.)
3. Restart your terminal

CLI Usage

Search notes

# Fuzzy search
notes search "recipe chocolate"

# Filter by folder
notes search "taxes" --folder "2024"

# Limit results
notes search "meeting" --limit 5

# Filter by date
notes search "project" --after 2024-01-01

Browse notes

# Recent notes
notes recent
notes recent --limit 10

# List all folders
notes folders

# Notes in a specific folder
notes folder "Recipes"
notes folder "Work" --limit 20

Read a note

# Get note ID from search results, then read full content
notes read 12345

Create a note

# Create a new note in the default "Notes" folder
notes create "Meeting Notes" --body "Agenda items for today..."

# Create in a specific folder
notes create "Shopping List" --body "Milk, eggs, bread" --folder "Personal"

Delete a note

# Delete a note by title
notes delete "Old Meeting Notes"

# Delete from a specific folder (useful if multiple notes have the same title)
notes delete "Draft" --folder "Work"

Manage index

# Show index statistics
notes stats

# Update index (incremental - only processes changed notes)
notes index

# Force full rebuild
notes index --force

The index uses incremental updates by default:

• Tracks modification timestamps to detect changed notes
• Only reprocesses notes modified since last index
• Detects and removes deleted notes
• Much faster than full rebuild for small changes

Claude Code Plugin

When installed as a plugin, you get:

Skill (auto-invoked): Claude automatically searches notes when you ask things like:

• "What's in my notes about recipes?"
• "Find my notes about the project"
• "Create a note about the meeting"
• "Delete my draft notes"

Slash Commands:

| Command | Description | |---------|-------------| | /notes:search <query> | Fuzzy search with optional filters | | /notes:recent | Show recently modified notes | | /notes:folders | List all folders with note counts | | /notes:folder "Name" | List notes in a specific folder | | /notes:read <id> | Read full note content by ID | | /notes:create <title> | Create a new note | | /notes:delete <title> | Delete a note by title |

MCP Server

Run as an MCP server for Claude Code integration:

notes --mcp

Available Tools

| Tool | Description | |------|-------------| | search_notes | Fuzzy search through notes | | recent_notes | Get recently modified notes | | read_note | Read full note content by ID | | list_folders | List all folders with note counts | | notes_in_folder | List notes in a specific folder | | get_note_stats | Get index statistics | | create_note | Create a new note | | delete_note | Delete a note by title |

Manual MCP Configuration

For Claude Desktop or VS Code, add to your MCP configuration:

{
  "mcpServers": {
    "notes": {
      "command": "npx",
      "args": ["-y", "@cardmagic/notes", "--mcp"]
    }
  }
}

PDF Text Extraction

PDF attachments in Notes are automatically extracted and indexed when:

1. pdftotext is installed - brew install poppler
2. PDF has been viewed - Notes caches PDFs locally when opened

The extracted text is appended to the note body, making PDF content fully searchable.

How it works

• PDFs are cached at ~/Library/Group Containers/group.com.apple.notes/Library/Caches/Paper/
• Each PDF bundle contains the file in Assets.bundle/
• Text is extracted using pdftotext and indexed with the parent note

Limitations

• PDFs stored only in iCloud (never opened locally) won't be indexed
• Password-protected PDFs cannot be extracted
• Scanned PDFs without OCR won't have searchable text

Data Locations

| Data | Path | |------|------| | Notes database | ~/Library/Group Containers/group.com.apple.notes/NoteStore.sqlite | | PDF cache | ~/Library/Group Containers/group.com.apple.notes/Library/Caches/Paper/ | | Search index | ~/.notes/index.db | | Fuzzy index | ~/.notes/fuzzy.json | | Stats | ~/.notes/stats.json |

Development

# Clone and install
git clone https://github.com/cardmagic/notes
cd notes
pnpm install

# Build
pnpm build

# Watch mode
pnpm dev

# Link globally for testing
pnpm link --global

# Type check
pnpm typecheck

# Lint
pnpm lint

Project Structure

src/
├── index.ts        # Entry point - routes to CLI or MCP
├── cli.ts          # Commander-based CLI
├── mcp.ts          # MCP server implementation
├── applescript.ts  # AppleScript automation for create/delete
├── indexer.ts      # Builds search indexes from Notes database
├── searcher.ts     # Query engine with fuzzy matching
├── attachments.ts  # PDF text extraction
├── formatter.ts    # Terminal output formatting
└── types.ts        # TypeScript types and utilities

Privacy

This tool accesses your local Notes database for reading and uses AppleScript to create/delete notes. No data is sent externally. The search index is stored locally in ~/.notes/.

License

MIT

Author

Lucas Carlson