Noteplan MCP Server

Official MCP server for NotePlan, the macOS/iOS markdown-based planner. Exposes notes, tasks, calendar, reminders, and plugins to AI assistants.

Collaboration by NotePlan None active

GitHub Docs npm: @noteplanco/noteplan-mcp

Overview

NotePlan MCP is the official Model Context Protocol server from NotePlan, the markdown-based planner that combines daily notes, project notes, tasks, and calendar events for macOS and iOS. The server runs locally on your Mac and exposes your NotePlan vault to AI assistants like Claude Desktop and Claude Code, supporting both the local file store and NotePlan's SQLite teamspace database.

The server provides 12 tool namespaces covering full CRUD on notes, task management with NotePlan's auto-formatted markers, native macOS Calendar and Reminders integration via EventKit, plugin and theme management, saved filter execution, AppleScript UI control, persistent user preference memory, and full-text search with property filters. Destructive operations use a two-step confirmation flow (a dry run returns a token that you must pass back to execute), and folders can be whitelisted or blacklisted via env vars.

Because the server runs entirely on your device, no authentication is required and no data leaves the machine unless you opt in to semantic embeddings, which require an OpenAI, Mistral, or custom-provider API key. NotePlan explicitly states the server is not designed to be exposed to the public internet.

Tools

Tool	Description
`noteplan_get_notes`	Retrieve single or multiple notes by id, title, filename, date, folder, or date range.
`noteplan_manage_note`	Lifecycle operations on notes: create, update, delete, move, restore, rename, and set/remove properties.
`noteplan_edit_content`	Mutate note content with insert, append, delete_lines, edit_line, or replace_lines.
`noteplan_paragraphs`	Line and task operations: get metadata, search within a note, search globally, add task, complete, update.
`noteplan_search`	Full-text search across notes with property filters; list tags and hashtags.
`noteplan_folders`	Folder and space operations: list, find, resolve, create, move, rename, delete.
`noteplan_filters`	Saved filter operations: list, get, execute, save, rename.
`noteplan_eventkit`	Access macOS Calendar and Reminders via EventKit; supports events and reminder lists.
`noteplan_memory`	Store, list, update, and delete persistent user preferences.
`noteplan_ui`	Control the NotePlan UI: open note, search, run plugin, toggle sidebar, capture screenshots.
`noteplan_plugins`	Plugin management: list, install, delete, read source/logs, create, screenshot.
`noteplan_themes`	Theme operations: list, get, save, set active.

Setup Guide

Prerequisites

macOS with NotePlan installed
Node.js 18 or higher (node -v)
Optional for building from source: Xcode Command Line Tools (xcode-select --install)

Install (Claude Code)

claude mcp add noteplan -- npx -y @noteplanco/noteplan-mcp

Install (Claude Desktop)

Open Settings > Developer > Edit Config and add:

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

Build from source

git clone https://github.com/NotePlan/noteplan-mcp.git
cd noteplan-mcp
npm install
npm run build

Optional environment variables

Variable	Purpose	Default
`NOTEPLAN_READ_ONLY`	Block all write actions	`false`
`NOTEPLAN_SKIP_DRY_RUN`	Skip the 2-step confirm for destructive writes	`false`
`NOTEPLAN_MCP_AUTOLAUNCH`	Activate NotePlan via AppleScript	`true`
`NOTEPLAN_ALLOWED_FOLDERS`	Whitelist folder prefixes	empty (all)
`NOTEPLAN_DENIED_FOLDERS`	Blacklist folder prefixes	empty
`NOTEPLAN_EMBEDDINGS_ENABLED`	Enable semantic search	`false`
`NOTEPLAN_EMBEDDINGS_PROVIDER`	`openai`, `mistral`, or `custom`	`openai`
`NOTEPLAN_EMBEDDINGS_API_KEY`	Required when embeddings are enabled	—
`NOTEPLAN_EMBEDDINGS_MODEL`	Model identifier	`text-embedding-3-small`
`NOTEPLAN_EMBEDDINGS_BASE_URL`	Custom endpoint	`https://api.openai.com`

The server auto-detects your NotePlan store under iCloud or the local container, plus the teamspace cache at ~/Library/Caches/teamspace.db.

Use Cases

Have Claude open today's daily note, summarize yesterday's incomplete tasks, and roll them forward into today's plan.
Generate a weekly review by searching notes with specific hashtags or properties and producing a digest of decisions, blockers, and follow-ups.
Bulk-edit notes across folders (e.g. retag, normalize frontmatter, or move archived project notes) using the manage_note and edit_content tools.
Bridge calendar and notes: pull macOS Calendar events for the day via EventKit and append a meeting note skeleton with attendees and action items.
Build or iterate on NotePlan plugins by listing installed plugins, reading their source, capturing screenshots, and pushing edits from Claude Code.

Example Prompts

"Show me all open tasks tagged #q3-launch across my project notes and group them by folder."
"Create today's daily note, add a 9am standup task, and append the agenda from yesterday's note."
"Search my notes for any paragraph mentioning 'Acme renewal' in the last 60 days and summarize the status."
"List my macOS Reminders due this week and mirror them as tasks under today's daily note."
"Read the source of my 'np.Templating' plugin and propose a fix for the latest error in its logs."

Pros

Official server maintained by NotePlan under the NotePlan GitHub org and @noteplanco npm scope.
Broad coverage: notes, tasks, folders, search, EventKit calendar/reminders, plugins, themes, UI control, and saved filters.
Runs entirely locally with no auth required; notes and calendar data never leave the device unless embeddings are opted in.
Safety features built in: read-only mode, folder allow/deny lists, and two-step dry-run confirmation for destructive operations.

Limitations

macOS-only in practice: depends on the local NotePlan store, EventKit, and AppleScript, so it cannot be run from Linux or Windows.
Semantic search requires bringing your own OpenAI, Mistral, or custom embeddings API key and is off by default.
Not designed for remote or multi-user deployment; documentation explicitly warns against exposing it to the internet.

Alternatives

Obsidian MCP server for markdown vaults in Obsidian.
Joplin MCP for the Joplin note-taking app.
OneNote MCP for Microsoft OneNote users.