@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/ai-marketplace
# 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/ai-marketplace
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/:
- Open System Settings > Privacy & Security > Full Disk Access
- Click + and add your terminal app (Terminal.app, iTerm, Warp, etc.)
- 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