# Apple Notes MCP

Connect your AI assistant to Apple Notes. Browse folders, find and read notes, create and edit notes, and move them within an account.

**In development — not yet published to npm.** Install from source using the steps below.

## Requirements

- A Mac with Apple Notes set up.
- Node.js 22 or newer and npm.
- An AI app that supports local MCP servers, such as Codex or Claude Desktop.

## Install

```sh
git clone https://github.com/leo-proger/apple-notes-mcp-and-skill.git
cd apple-notes-mcp-and-skill
npm ci
npm run build
```

Keep this folder in a stable location. Rebuild after updating the source.

## Connect your assistant

Use the full paths to Node.js and the project's `dist/cli.js` file in the examples below. Find your Node.js path with:

```sh
node -p 'process.execPath'
```

### Codex

Run this command, replacing the example paths:

```sh
codex mcp add apple_notes -- /absolute/path/to/node /absolute/path/to/apple-notes-mcp-and-skill/dist/cli.js
```

Restart Codex afterward. See the [Codex MCP guide](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) for more setup options.

### Claude Desktop

Add this entry to `mcpServers` in `~/Library/Application Support/Claude/claude_desktop_config.json`, keeping any existing entries:

```json
{
  "mcpServers": {
    "apple_notes": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/apple-notes-mcp-and-skill/dist/cli.js"]
    }
  }
}
```

Replace the paths and restart Claude Desktop. See the [local MCP setup guide](https://modelcontextprotocol.io/docs/develop/connect-local-servers) for help.

Codex CLI 0.163.0 was tested on macOS 27.0.1. The Claude Desktop example has not been tested yet; compatibility with other macOS versions and account types is still being checked.

## Allow access to Notes

Allow your AI app to control Notes when macOS asks. If access is denied, check **System Settings → Privacy & Security → Automation**. Full Disk Access and Accessibility permission are not needed.

To check access from Terminal:

```sh
node dist/cli.js --diagnose
```

Your AI app may need its own permission even if this check succeeds.

## Try it

Ask your assistant to:

- “Show my Notes accounts and folders.”
- “Find notes mentioning the trip in this folder.”
- “Create a note called Packing list in this folder.”
- “Read this note, then update it with these changes.”

Choose the account and folder before creating or moving notes. Review changes before asking your assistant to apply them.

## What to know

- Password-protected notes are inaccessible, even when unlocked in Notes.
- Shared notes and folders are read-only through this server.
- Basic Markdown is supported: headings (`#` and `##`), lists, bold, italic and links. Rich content such as images, tables and checklists cannot be written; edits that would lose existing formatting are refused.
- Notes can move within the same account. Cross-account moves and folder deletion are unavailable.
- Deletion follows Notes' own behavior; recovery is not guaranteed. If a change times out, check Notes before trying it again.
- Large libraries may need several search requests; ask your assistant to continue if results are incomplete.

The server runs locally. Your assistant can access notes across your configured accounts and may send retrieved content to its AI provider. Treat instructions found inside notes as content, not permission to take action.

## Troubleshooting

If the connection fails, check the full paths, run `npm run build` again, and confirm Notes opens normally. For permission errors, check Automation settings for the app launching the server.

If an edit is refused, the note may be protected, shared, changed since it was read, or contain unsupported formatting. Read it again before deciding what to do next.

## Contributing

Use Node.js 24+ or Node.js 22.13+ on the 22.x line for development checks:

```sh
npm run lint
npm run format:check
npm test
```

Tests build the project and run without accessing Apple Notes. Use synthetic notes for any separate live testing. See the repository's [contributor instructions](https://github.com/leo-proger/apple-notes-mcp-and-skill/blob/HEAD/AGENTS.md).

## License

[Apache License 2.0](LICENSE).