Notion-Desktop-MCP
This MCP server controls the Notion Desktop app through debug mode, letting an AI agent inspect, edit, and manage Notion pages and databases locally.
Launch or restart Notion in debug mode, or switch it back to normal mode.
Check connection status, workspace, open tabs, active page, and access level.
Open pages by URL or ID.
Read page structure via outline or Markdown content.
Insert Markdown as new blocks, including headings, lists, to-dos, quotes, code, Mermaid diagrams, tables, and links.
Create a full Notion database in one step from a Markdown table.
Preview and confirm block deletions, with local Markdown backups.
List past deletions and restore deleted blocks where they were.
Move pages to Notion Trash and restore pages or databases from Trash.
Switch between Notion workspaces/accounts.
Take screenshots of the active Notion page.
Run custom Playwright code through an escape hatch for advanced Notion UI automation.
Controls the Notion Desktop app through its debug port, allowing AI agents to open and read pages, insert Markdown as blocks, create databases from tables, delete and restore blocks or trash/restore pages, switch workspaces, take screenshots, and run Playwright-based Notion operations.
Notion-Desktop-MCP
An MCP server that lets AI agents control the Notion Desktop app on your computer. It ships as a
Claude Code plugin and works with any other MCP client (Cursor, VS Code, Codex CLI, Gemini CLI and
others). It connects through Notion's debug mode. Notion starts with a remote debugging port
(localhost:9222), and the server drives the app over that port, the way browser automation tools
drive Chrome.
⚠️ Use at your own risk. An AI agent edits your real Notion content, and the debug port is open to local programs while it runs. Read Disclaimer and risks before you install.
Why use it instead of the official Notion connector
Official Notion MCP / API | Notion-Desktop-MCP | |
Sign-in | OAuth or an integration token | None. Uses the Notion Desktop app you are already logged in to |
Workspace admin | An owner or admin often has to approve or install the integration | No admin step. Nothing is installed in the workspace |
Page access | Pages must be shared with the integration | Every page you can open in the app |
Guest workspaces | Usually not reachable (guests cannot add integrations) | ✅ Works wherever you are a guest with edit access |
Runs where | Notion's servers / API | Your own computer, against your local Notion Desktop |
In short: if Notion Desktop is logged in on your PC, the agent can work in it. It does not work with Notion in a web browser.
Not needing approval is a technical fact, not permission. Your organisation's rules on automation and AI tools still apply; see Disclaimer and risks.

Real recording. One notion_insert call writes a 12-block section (headings, numbered list, to-dos,
code). One notion_create_database call then builds a 6-row database. The calls took about 5 s and
11 s.
Related MCP server: Notion Knowledge Base MCP Server
How it works
AI agent ──MCP──▶ notion-desktop-mcp server ──CDP──▶ Notion Desktop in debug mode (localhost:9222)notion_launchrestarts Notion Desktop with--remote-debugging-port=9222. Notion saves continuously, so the restart loses nothing.The MCP server connects to that port with Playwright and exposes Notion-specific tools.
On connect, the server sends every client short usage and safety instructions. Claude Code also loads the full skill (
skills/notion-desktop-mcp/SKILL.md).
Without debug mode the tools cannot connect. Switching Notion back to normal mode closes the port.
Install
All installs need Node.js 18 or newer and the Notion Desktop app. Pick the section for your agent.
Claude Code
claude plugin marketplace add felixhorobot/Notion-Desktop-MCP && claude plugin install notion-desktop-mcp@notion-desktop-mcpThe same two steps from inside Claude Code:
/plugin marketplace add felixhorobot/Notion-Desktop-MCP
/plugin install notion-desktop-mcp@notion-desktop-mcpRestart Claude Code and ask it to "start Notion in debug mode". Claude calls notion_launch. The
first start also installs the server's npm packages, which takes about 30 s.
git clone https://github.com/felixhorobot/Notion-Desktop-MCP
cd Notion-Desktop-MCP
powershell -ExecutionPolicy Bypass -File install.ps1The script installs the dependencies, registers the MCP server, links the skill into
~/.claude/skills/notion-desktop-mcp, and adds two desktop shortcuts: Notion (Claude debug) and
Notion (normal). If you installed the plugin, run install.ps1 -ShortcutsOnly from a clone to get
only the shortcuts.
Other AI agents
npx fetches the server from GitHub and runs it, so there is no separate download. Besides Node.js,
this needs Git.
npx -y github:felixhorobot/Notion-Desktop-MCPRegister that command as an MCP server in your client. One-line setup where the client has a command for it:
Client | Command |
VS Code (Copilot agent mode) |
|
Codex CLI |
|
Gemini CLI |
|
Clients configured with a JSON file (Cursor: ~/.cursor/mcp.json; Windsurf:
~/.codeium/windsurf/mcp_config.json; Claude Desktop: claude_desktop_config.json) take this entry:
{
"mcpServers": {
"notion-desktop-mcp": {
"command": "npx",
"args": ["-y", "github:felixhorobot/Notion-Desktop-MCP"]
}
}
}On Windows, if a client cannot start npx, use "command": "cmd" with
"args": ["/c", "npx", "-y", "github:felixhorobot/Notion-Desktop-MCP"].
Then ask the agent to start Notion in debug mode (notion_launch). Every client receives the server's
safety instructions on connect. For the full guide, add skills/notion-desktop-mcp/SKILL.md to the
agent's own instruction file (for example AGENTS.md, GEMINI.md or a Cursor rule).
Only Claude Code and the npx start have been tested. The client commands above follow each client's
documented MCP setup; please report any that do not work.
Supported systems
System | Status |
Windows 11 | ✅ Built and tested on Notion Desktop 7.41.1 (Microsoft Store version) |
Windows 10 | 🟡 Same app and launcher; not tested |
macOS | 🟡 Not tested yet (details below) |
Linux | ❌ Notion has no official desktop app for Linux |
macOS. The server, relay and skill are plain Node.js and run on any system. Keyboard shortcuts use
Playwright's ControlOrMeta, which becomes ⌘ on a Mac. A Mac launcher, launcher/notion.sh, restarts
Notion with --remote-debugging-port=9222. Two points are still open:
Whether Notion Desktop for Mac accepts
--remote-debugging-port. Most Electron apps do; some disable it.Small differences in the Mac interface that could break a selector.
To check the first point, run launcher/notion.sh debug and then
curl http://localhost:9222/json/version. A JSON reply means debug mode works. Please open an issue
with your result.
What it can do
Write a whole section in one call
Headings, a quote, to-dos, a table and a horizontal Mermaid roadmap, all from one notion_insert.

Links to blocks, databases and websites

Related databases
Owners and Tasks are real Notion databases. Each task links to its owner through a relation, and
the Status and Area properties are filled in.

Board views

Create a database in one step
notion_create_database pastes a Markdown table and converts it to a database. The 6 × 4 table below
took one call. Filling the same cells one at a time takes about 1 s per cell.

Delete with a backup, then restore
A delete only previews until you confirm it. Each deleted block is saved as Markdown first, and
notion_restore_blocks puts it back in the same place.

The "This week" section is deleted, then restored to the same position with its ticks intact.
Tools
Tool | What it does |
| Restart Notion Desktop in debug mode, or back to normal mode |
| Connection, workspace, open tabs, access level |
| Open a page by URL or id |
| Every block with its id / the page as Markdown |
| Add Markdown as blocks; undoes its paste if an existing block disappears |
| Build a database from a Markdown table in one step |
| Preview, then delete with |
| List past deletes; put blocks back where they were |
| Move a page to Notion Trash and back, by URL or title |
| Switch workspace or account; take a screenshot |
| Run Playwright code with the |
The skill in skills/notion-desktop-mcp/SKILL.md covers the tools, Notion behaviour verified on the live
app, and the rules for shared workspaces.
Safety
These rules are enforced by the server, not left to the prompt:
Deleting blocks and trashing pages only preview until
confirm: trueis passed.In guest or shared workspaces, and whenever the server cannot identify the workspace, deletes are refused unless
allow_shared: trueis also passed. The server's instructions tell the agent to pass it only after you agree.Block backups are stored in
~/.notion-desktop-mcp/deletions.jsonl. Restored blocks get new ids. Colours, the open or closed state of toggles, and code languages other than Mermaid are not kept.Child pages and databases go to Notion Trash, which keeps them for 30 days.
notion_restore_pagebrings them back.Each insert compares the whole page before and after, scrolling to include blocks Notion has unloaded. If a block that existed before is missing, the insert undoes its own paste.
Privacy
Everything runs on your own computer. The project has no server, no telemetry and no analytics, and it sends nothing to the author or any third party.
Notion content passes only between Notion Desktop and the AI agent you connect. What the agent does with it (for example, sending it to its model provider) is governed by that agent's own terms.
Block backups are stored locally in
~/.notion-desktop-mcp/deletions.jsonl. Delete that file at any time to remove them.
Speed
Send a whole section per
notion_insert. It is one paste, whatever the number of blocks.Use
notion_create_databasefor tables of data. It is one step instead of one action per cell.Per-cell edits (
n.db.setOptionand similar, throughnotion_run_code) take about 1 s each. Use them to set property types or fix single values.The server connects to Notion on the first call and stays connected, so later calls skip that step.
Security
While Notion Desktop runs in debug mode, any program on your computer can connect to
localhost:9222 and act as you in Notion, including reading your session. The port accepts local
connections only. Use debug mode on a computer you trust, and switch back to normal mode
(notion_launch with mode: "normal") when you finish. notion_run_code runs any code you give it
against Notion; Claude Code asks for permission before running it unless you have allowed the tool.
Disclaimer and risks
You use this software at your own risk and are responsible for what it does in your Notion.
Not official. This is an independent project. It is not affiliated with, endorsed by or supported by Notion Labs, Inc. or Anthropic. "Notion" is a trademark of Notion Labs, Inc.
AI agents make mistakes. An agent can edit, move or delete content you did not intend to change. The backup covers only blocks deleted through
notion_delete_blocks. Edits to existing text, property changes and actions run throughnotion_run_codehave no backup. Try it on a private test page first, review what the agent plans before it acts in shared workspaces, and rely on Notion's own page history and Trash for recovery.Unofficial interface. The server drives Notion's interface through a debugging port that Notion does not offer as an automation API. A Notion update can break it without notice.
Terms and policies. Check that automating the Notion app is allowed under Notion's terms and under your organisation's or workspace's policies, especially for work and shared workspaces.
Local security. While debug mode is on, other programs on your computer can control Notion (see Security).
No warranty. The software is provided "as is", without warranty of any kind, as stated in the MIT License. The authors are not liable for data loss or any other damage from its use.
Credit
Created by felixhorobot. You may fork, change and reuse this
project under the MIT License. The license requires you to keep the copyright notice: keep the
LICENSE file and credit the original project, for example:
Based on Notion-Desktop-MCP by felixhorobot.
Development
npm install
node server/test/call.mjs # list the tools
node server/test/call.mjs notion_status '{}' # call one tool
node server/test/roundtrip.mjs <scratch-page-url> # delete/restore round trip on a page you ownskills/notion-desktop-mcp/scripts/selftest.js runs 22 checks on the page.n helpers; run it with
notion_run_code in a private workspace. The tools drive Notion's interface, so run both tests again
after each Notion update.
Path | Contents |
| MCP server and tools |
| Relay that hides Notion's unresponsive debug targets and keeps your theme |
| Entry point; installs dependencies on first run |
| The skill: |
|
|
License
MIT © felixhorobot
Available Tools
15 toolsnotion_create_databaseA
Create a full database in ONE step from a Markdown table (header row = property names, other rows = entries). Much faster than adding rows/cells one by one: pastes the table, turns it into a database and names it. Columns start as text; change types afterwards with notion_run_code (n.db.headerMenu) if needed.
Inputs: table (required), title (required), page, after, +1 more.
notion_delete_blocksA
Delete blocks by id. Without confirm:true it only previews. Text blocks are saved as Markdown to the local deletion log (restore with notion_restore_blocks); child pages and databases go to Notion Trash (restore with notion_restore_page). Guest/shared workspaces also need allow_shared:true; only after the user said yes.
Inputs: block_ids (required), page, confirm, allow_shared.
notion_insertA
Insert Markdown as new blocks (headings, lists, to-dos, quotes, code incl. ```mermaid, tables, links). Never edits existing blocks; rolls back if any existing block disappears.
Inputs: markdown (required), page, after, position.
notion_launchA
Start (or restart) Notion in debug mode so the other tools can connect, or back to normal mode. It RESTARTS Notion (nothing is lost, Notion saves continuously); ask the user first. Windows tested; macOS untested.
Inputs: mode.
notion_list_deletionsB
List blocks deleted through this server (newest first) with their Markdown backups.
Inputs: limit.
notion_openB
Open a Notion page by URL or id in the active tab.
Inputs: url (required).
notion_outlineA
List the page blocks as [depth, type, id, first 80 chars]. Use the ids for insert/delete.
Inputs: page.
notion_readB
Read the page (or some blocks) as Markdown.
Inputs: page, block_ids.
notion_restore_blocksA
Put deleted blocks back where they were (as new blocks, from the Markdown backup). Default: the latest unrestored deletion. Child pages/databases are not in the backup; use notion_restore_page for those.
Inputs: deletion_id.
notion_restore_pageA
Restore a page or database from Notion Trash, by URL (opens it and clicks "Restore page") or by exact title (searches the sidebar Trash of the current workspace).
Inputs: url, title.
notion_run_codeA
Escape hatch: run async (page) => {...} against the target page (Playwright Page with page.n helpers: n.db., n.table., n.tabs.*, n.slash, n.guard… see SKILL.md). Prefer the dedicated tools; never delete with this; use notion_delete_blocks so a backup exists.
Inputs: code (required), page.
notion_screenshotB
Screenshot of the active Notion page (to check layout/diagrams).
Inputs: page.
notion_statusA
Check the connection: debug port, workspace, open tabs, active page and access level. Call first.
Inputs: no named parameters.
notion_switch_workspaceB
Switch the Notion window to another workspace/account by name. Tell the user, and switch back when done.
Inputs: name (required).
notion_trash_pageA
Move the current page to Notion Trash (30 days, restorable). The title must match exactly. Without confirm:true it only previews. Guest workspaces usually disallow this.
Inputs: title (required), page, confirm, allow_shared.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Most tools have clearly distinct roles (outline vs read, insert vs delete, trash_page vs restore_page). The closest overlaps are notion_delete_blocks vs notion_trash_page and notion_restore_blocks vs notion_restore_page, but descriptions explicitly clarify the block-vs-page distinction. notion_run_code overlaps everything but is explicitly framed as a last-resort escape hatch, which mitigates the ambiguity.
Every tool uses a consistent notion_ prefix with lowercase snake_case, making the set highly predictable. Minor deviations: some names are bare verbs (notion_read, notion_insert, notion_open) while others are verb_noun (notion_create_database, notion_delete_blocks), and a couple are noun-only (notion_status, notion_screenshot).
Fifteen tools sit at the top of the well-scoped range and each maps to a real workflow step: connection/status, navigation, reading, writing, deletion/restore lifecycle, and workspace switching. No obviously redundant tool bloats the set.
Read, insert, delete/restore, trash/restore, and page creation from Markdown tables are covered, but there is no tool to edit existing block content (notion_insert explicitly never edits) and no general page search by title. Database operations beyond one-shot creation (adding rows, changing property types) fall back to notion_run_code rather than a dedicated tool, which is a notable gap for a Notion surface.
Maintenance
Related MCP Connectors
Hosted Notion MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
An MCP server that gives your AI access to the source code and docs of all public github repos
Hosted YouTube MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP Server for the Notion API, enabling Claude to interact with Notion workspaces.313,089 npm925MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that connects to your Notion knowledge base, allowing you to query and retrieve information directly from VSCode using the Cline extension.-
- AlicenseNot gradedqualityAmaintenanceLocal-first knowledge base MCP server. Lets AI agents (Claude Code, Cursor, etc.) read and write your personal knowledge base through 20 MCP tools. Zero cloud dependency — all files stay on your machine.707MIT
- AlicenseNot gradedqualityAmaintenanceA local-first MCP server that helps Claude Code prioritize your work by searching across your tools like GitHub and Slack.7 npmMIT