Skip to main content
Glama
niranjhan-si

notesMCP

by niranjhan-si
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

notesMCP

An MCP server that gives Claude read/write access to Apple Notes on macOS.

Apple Notes has no public API, so this shells out to osascript -l JavaScript (JXA) to drive Notes.app directly — the same approach every other Apple Notes integration uses.

Tools

Tool

Description

list_folders

List all Notes folders

list_notes

List notes, optionally scoped to a folder

get_note

Get a note's full body by id or exact title

search_notes

Search titles/bodies for a substring

create_note

Create a note (title, body, optional folder)

update_note

Replace or append to a note's body

delete_note

Delete a note (moves to "Recently Deleted")

Related MCP server: Apple Notes MCP Server

Prerequisites

  • macOS with Notes.app

  • Node.js 18+

  • The first time a tool runs, macOS will prompt for permission to let your terminal/Claude Code automate Notes — grant it in System Settings → Privacy & Security → Automation.

Install

git clone https://github.com/niranjhan-si/notesMCP.git
cd notesMCP
npm install

Register with Claude Code

claude mcp add --scope user notesmcp -- node "$(pwd)/src/index.js"

--scope user makes it available in every Claude Code session, not just this project. Verify with claude mcp list.

Test

npm test

Creates a real throwaway note, runs it through create/get/search/update/list/delete, then leaves it in "Recently Deleted" (Notes.app's normal soft-delete).

Error handling

Every failure returns a specific message instead of a generic crash: permission not granted, Notes.app not reachable, note/folder not found, a password-locked note, or a timeout on a very large library.

Errors fall into two kinds:

  • User-fixable (permission, not found, locked note) — the message tells you what to do; nothing more happens.

  • Everything else (an actual bug in this tool) — the message includes a link that opens a pre-filled GitHub issue. Nothing is ever sent automatically; you review and submit it yourself, or not.

Notes on the design

  • Plain Node.js, no build step — the whole server is three files (notes.js, errors.js, index.js).

  • Notes are matched by id (preferred) or exact title. Duplicate titles resolve to the first match; that's a known limitation, not a bug.

  • delete_note mirrors Notes.app's own behavior: it moves the note to "Recently Deleted" rather than purging it immediately.

  • osascript's default output mangles JSON-looking strings (see build log), so every JXA call runs with -s s and gets parsed twice.

See docs/BUILD_LOG.md for how this was built.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers