NoteAgent

Your AI coding agent's secondary brain.

NoteAgent is an MCP (Model Context Protocol) server that connects AI coding agents — Claude Code, Cursor, OpenCode — with Apple Notes. Use it to capture debug sessions, log commit context, save code snippets, and manage notes without leaving your terminal.

Built for developers who think in code and organize in notes.

Quick Start

# Run directly (no install needed)
npx apple-notes-agent-mcp

# Or install globally
npm install -g apple-notes-agent-mcp
apple-notes-agent-mcp

Why NoteAgent?

Existing Apple Notes MCP servers are generic note managers. NoteAgent is built for developers:

• Developer workflows — Pre-built templates for standups, debug sessions, commit logs
• Code snippet capture — Save language-aware snippets with file path context
• Zero config — npx apple-notes-agent-mcp just works on macOS
• Health checks — doctor tool verifies Notes.app permissions and connectivity
• Error recovery — Automatic retries with exponential backoff and clear error messages

Installation

Requirements

• macOS with Apple Notes.app
• Node.js >= 18
• Terminal/IDE with automation permissions (System Settings → Privacy & Security → Automation)

npm (recommended)

npx apple-notes-agent-mcp

Local development

git clone https://github.com/jayprajapati/apple-notes-agent-mcp.git
cd apple-notes-agent-mcp
npm install
npm run build
node dist/index.js

MCP Client Configuration

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "noteagent": {
      "command": "npx",
      "args": ["apple-notes-agent-mcp"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "noteagent": {
      "command": "npx",
      "args": ["apple-notes-agent-mcp"]
    }
  }
}

OpenCode

Add to your MCP configuration file:

{
  "mcpServers": {
    "noteagent": {
      "command": "npx",
      "args": ["apple-notes-agent-mcp"]
    }
  }
}

Tools (15 total)

Note Operations

| Tool | Description | |------|-------------| | create_note | Create a new note with title and content | | get_note | Get a note's content by title or ID | | update_note | Update a note (replace, append, or prepend) | | delete_note | Delete a note by title or ID | | list_notes | List notes in a folder or account | | move_note | Move a note to a different folder |

Folder Operations

| Tool | Description | |------|-------------| | create_folder | Create a new folder | | delete_folder | Delete a folder | | list_folders | List all folders with note counts |

Search & Account

| Tool | Description | |------|-------------| | search_notes | Search notes by keyword | | list_accounts | List available Notes accounts | | get_recent_notes | Get notes modified in last N hours/days |

Developer Workflows

| Tool | Description | |------|-------------| | create_dev_note | Create a developer-formatted note (standup, debug, commit) | | create_snippet_note | Save a code snippet with language and context | | doctor | Run diagnostics on Notes.app connectivity and permissions |

Usage Examples

Create a note

Create a note titled "Meeting Notes" in the "Work" folder with today's action items.

The agent will use create_note with your content. Folders are created automatically if they don't exist.

Debug session logging

Log this debugging session as a dev note. The issue was a race condition in the auth middleware.
Steps to reproduce: send two concurrent login requests.
Root cause: shared mutable state in session store.
Fix: use atomic operations.

The agent will use create_dev_note with the debug template.

Save a code snippet

Save this code snippet to my notes — it's a TypeScript utility function from src/utils.ts

The agent will use create_snippet_note with the file path and language context.

Search notes

Search my notes for anything about "deployment pipeline"

Health check

Check if Notes.app is working properly with NoteAgent

The agent will run doctor to verify permissions and connectivity.

Daily standup

Create a standup note for today. I finished the auth module and started on the API layer.

The agent will use create_dev_note with the standup template.

Developer Templates

Daily Standup (standup)

Pre-formatted with:

• What I did yesterday
• What I'll do today
• Blockers

Debug Session (debug)

Pre-formatted with:

• Issue description
• Steps to reproduce
• Root cause analysis
• Fix applied

Commit Log (commit)

Pre-formatted with:

• Commit message
• Files changed
• Context notes

Code Snippet (snippet)

Includes:

• Language tag
• File path context
• Formatted code block

Troubleshooting

"Apple Notes access denied"

Grant automation permissions:

1. Open System Settings
2. Go to Privacy & Security → Automation
3. Enable access for your terminal app (Terminal, iTerm2, VS Code, etc.)

"Apple Notes is not running"

Open Notes.app before using NoteAgent. The MCP server communicates with Notes via AppleScript.

Notes not found

NoteAgent searches by exact title match. Use list_notes or search_notes to find the correct title.

Connection issues

Run the diagnostic tool:

Run the doctor tool to check NoteAgent status

This verifies Notes.app is installed, running, and accessible.

Architecture

src/
├── index.ts                 # MCP server entry point
├── types.ts                 # TypeScript interfaces
├── services/
│   ├── applescript.ts       # AppleScript executor with retry logic
│   └── notes-manager.ts     # High-level Notes operations
├── tools/
│   ├── note-tools.ts        # 6 note CRUD tools
│   ├── folder-tools.ts      # 3 folder management tools
│   ├── search-tools.ts      # 3 search/account tools
│   └── developer-tools.ts   # 3 developer workflow tools
└── utils/
    ├── helpers.ts           # Shared utilities
    └── parsing.ts           # AppleScript output parsing

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run integration tests (requires Notes.app)
npm run test:integration

# Type check
npm run lint

License

MIT