How to Install the NotePlan MCP Server

The NotePlan MCP server connects NotePlan to AI clients, so you can manage notes, tasks, reminders, and calendar items by chat.

There are two versions. Use the one that matches your NotePlan version:

  • NotePlan 3.22 and later: the MCP server is built into NotePlan. You install it from the Help menu, and you don't need Node.js. Go to the instructions.
  • NotePlan 3.21 and earlier: the MCP server runs with Node.js. Go to the instructions.

Note: NotePlan 3.22 is available on TestFlight now. To see your version, open NotePlan > About NotePlan.

NotePlan 3.22 and later (built-in)

What You Need

Step 1 — Remove the old connector (if you used it)

If you installed the Node.js version before, remove it first. Otherwise your AI client shows two sets of NotePlan tools.

  • Claude Desktop: open Settings > Developer > Edit Config, delete the "noteplan" entry under mcpServers, save, and quit Claude Desktop with ⌘Q.
  • Claude Code: run claude mcp remove noteplan
  • Codex: run codex mcp remove noteplan

Step 2 — Install the connector

All install options are in NotePlan on your Mac, in the menu Help > AI Connectors (MCP).

Claude Desktop

  1. In NotePlan, choose Help > AI Connectors (MCP) > Install Claude Connector…
  2. Claude Desktop opens its install dialog for NotePlan. Click Install. If the dialog shows Uninstall, the connector is already installed.

Claude Code

  1. Click Copy Claude Code Command.
  2. Paste the command into Terminal and press Return.
  3. Run claude mcp list to check that noteplan-cli is connected.

ChatGPT and Codex

  1. Click Install Codex / ChatGPT Connector…, then Copy Command and Open Terminal.
  2. Paste the command into Terminal and press Return.
  3. Restart ChatGPT or Codex.

Other MCP clients

Click Copy MCP Configuration and paste it into the MCP settings of your client. The server command is the NotePlan app itself with the argument mcp-server, e.g. /Applications/NotePlan.app/Contents/MacOS/NotePlan mcp-server.

Step 3 — Try It

  • "What's on my schedule today?"
  • "Show my open tasks tagged #urgent."
  • "Add a task to my Daily Note: call the dentist at 3pm."
  • "Which tasks did I complete this week in my project folders?" (the AI can use the advanced search operators, e.g. done:this-week)

Good to Know

  • NotePlan can be closed. The connector uses NotePlan's own note engine and works with NotePlan closed. NotePlan syncs the changes when it runs (right away if it is open).
  • Some actions open NotePlan in the background: rendering templates, running plugins, screenshots, changes to Spaces, and calendar or reminder actions from a terminal client (Claude Code, Codex CLI).
  • Updates are automatic. The connector is part of NotePlan, so each NotePlan update also updates the connector. You don't need to install it again.
  • Changes apply right away. There is no preview step. Trashed notes can be restored from @Trash.
  • Command line: you can use the same tools without an AI client. Run /Applications/NotePlan.app/Contents/MacOS/NotePlan cli help in Terminal.

Troubleshooting (3.22 and later)

"Your Notes Sync with iCloud Drive"

The connector reads notes stored with CloudKit sync or locally. If your notes sync with iCloud Drive, it reports an error. Switch to CloudKit sync in Settings > Sync.

NotePlan tools show up twice

The old Node.js connector is still installed. Remove it (see Step 1) and restart your AI client.

Claude isn't using the NotePlan tools

  • Check that the connector is on: Claude Desktop > Settings > Extensions > NotePlan.
  • Quit Claude Desktop with ⌘Q, relaunch it, and start a new conversation.

Logs for support

The connector writes its log to ~/Library/Containers/co.noteplan.NotePlan3/Data/Library/Logs/NotePlan-headless.log (Setapp: co.noteplan.NotePlan-setapp instead of co.noteplan.NotePlan3). In Finder, use Go > Go to Folder and paste the path. Send us this file if we ask for logs.

NotePlan 3.21 and earlier (Node.js)

What You Need

  • A Mac with NotePlan installed
  • Node.js 18 or newer
  • Claude Desktop, Claude Code or OpenAI Codex (see the links above)

Step 1 — Install Node.js

If you don't have Node.js yet, install it from https://nodejs.org.

Step 2 — Connect NotePlan MCP

Claude Desktop

  • Open Claude Desktop.
  • Go to Settings > Developer > Edit Config.
  • Replace the config with:
{
  "mcpServers": {
    "noteplan": {
      "command": "npx",
      "args": ["-y", "@noteplanco/noteplan-mcp"]
    }
  }
}
  • Save and restart Claude Desktop.

Claude Code

Run:

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

OpenAI Codex (CLI)

Codex runs with your ChatGPT account/subscription.

Run:

codex mcp add noteplan -- npx -y @noteplanco/noteplan-mcp
codex mcp list

OpenAI Codex (UI)

Go to Settings > MCP servers > Add new server, then fill:

  • Name: noteplan
  • Command to launch: npx (or /usr/local/bin/npx)
  • Arguments: -y, @noteplanco/noteplan-mcp
  • Working directory: keep default (for example ~/code)

The npx command automatically downloads and runs the NotePlan MCP server.

Troubleshooting (3.21 and earlier)

How to view MCP logs (Claude Desktop)

Logs are the fastest way to diagnose MCP issues. To find them:

  • Open Claude Desktop Settings (⌘ + , on Mac).
  • Click Developer, then click the NotePlan MCP server entry.
  • Click View Logs — this opens the log file in Console.app.
  • In Console.app, click Reveal in Finder (at the top) to see the log file on disk.

The log file is typically located at:

~/Library/Logs/Claude/mcp-server-noteplan.log

"No such file or directory" on startup

If Claude Desktop shows env: node: No such file or directory or Failed to spawn process, it usually means Node.js was installed with a version manager (like n, nvm, fnm, or volta) and Claude Desktop can't find it.

To fix this, open Terminal and run:

which npx

This will show the full path, for example /Users/you/.n/bin/npx. Take the folder part (/Users/you/.n/bin) and update your Claude Desktop config:

{
  "mcpServers": {
    "noteplan": {
      "command": "npx",
      "args": ["-y", "@noteplanco/noteplan-mcp"],
      "env": {
        "PATH": "/Users/you/.n/bin:/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin"
      }
    }
  }
}

Replace /Users/you/.n/bin with the folder from your which npx output. Save and restart Claude Desktop.

Claude isn't using the NotePlan tools

If Claude responds to your question without using the NotePlan tools (you don't see a tool use indicator in the response), try these steps in order:

  • Delete the MCP log file. Find it using the steps under "How to view MCP logs" above, then delete the file.
  • Fully restart Claude Desktop. Quit with ⌘Q (not just close the window), then relaunch.
  • Start a new conversation. Open a fresh Chat conversation (not Cowork).
  • Tell the AI to refresh. In your new conversation, try sending: "The NotePlan MCP tools have been updated. Please refresh your tool list and show me my calendar events for today." — this nudges the AI to re-check the available tools instead of relying on cached information.

Claude Desktop can sometimes cache stale MCP tool metadata. Restarting and starting a fresh conversation clears this.

Calendar or Reminders access not working

The Node.js server accesses your calendars and reminders through NotePlan via AppleScript. For this to work:

  • NotePlan must be running. If NotePlan isn't open, calendar and reminder commands will fail.
  • NotePlan must be up to date. Calendar and reminder support requires NotePlan 3.20.2 or later.

Sending logs for support

If something isn't working, we may ask you for your MCP logs. To get a clean log:

  • Quit Claude Desktop (⌘Q).
  • Delete the existing log file (see "How to view MCP logs" above for the location).
  • Relaunch Claude Desktop.
  • Open a new Chat conversation and reproduce the issue.
  • Open the new log file and send us the full contents.

A fresh log makes it much easier to diagnose the problem.