Notion Private API MCP Server

> An unofficial Notion MCP server built on Notion's private API (token_v2). It gives
> Claude Desktop, Claude Code, Cursor and any other MCP client full read/write access to your
> entire Notion workspace — with no integration token and without sharing pages one by one.

Unlike servers built on the official Notion API, this one authenticates with your browser
session cookie, so an LLM agent can search, read, create and edit any page your account can
see — instantly, with zero setup in Notion. Built on the official
@modelcontextprotocol/sdk (stdio transport).

---

Why this server?

| | This server (private API) | Official Notion API / MCP |
|---|---|---|
| Setup in Notion | None — just your browser cookie | Create an integration + share each page |
| Access scope | Everything your account can see | Only pages explicitly shared with the integration |
| Auth | token_v2 session cookie | Integration token / OAuth |
| Best for | Personal automation, full-workspace agents | Production apps, multi-user, official support |
| Stability | ⚠️ Fragile, undocumented | ✅ Stable, supported |

If you just want an agent over your own workspace without fighting integration permissions,
this is the fastest path. For production / multi-tenant apps, use the
official Notion MCP server.

---

Table of contents

- Important: private API
- Quick start
- Tools
- Configuration
- Usage with MCP clients
- Example prompts
- Writing content
- Troubleshooting / FAQ
- Contributing
- License · Disclaimer

---

⚠️ Important: this uses Notion's private API

This server talks to Notion's undocumented internal API (https://www.notion.so/api/v3),
not the official public API:

- Auth is your browser cookie (token_v2) — effectively your account password. Never commit it.
- Notion can change or break this API at any time, and using it may be against Notion's ToS.
- It is inherently fragile and not for production — use at your own risk, with your own data.

---

Quick start

git clone https://github.com/kirvigen/notion-private-api-mcp.git
cd notion-private-api-mcp
npm install
export NOTION_TOKEN_V2='your_token_v2'   # see "Configuration" below
npm start

Then register it in your MCP client (Claude Desktop / Claude Code).

---

Tools

| Tool | Description |
|---|---|
| get_page | Read a page block and its metadata |
| get_block | Read a single block |
| get_block_children | Read the direct child blocks of a page or block |
| get_style_documentation | Catalog of supported block types & inline annotations (call before composing complex pages) |
| markdown_to_blocks | Preview how Markdown parses into the simplified block JSON |
| create_page | Create a child page under another page, from blocks or Markdown |
| append_blocks | Append blocks/Markdown to a page (at the end, or after a given block) |
| replace_page_content | Replace the direct child blocks of a page |
| update_block_text | Replace the plain-text content of a block (e.g. a code block) |
| delete_blocks | Remove (archive) direct child blocks from a page |
| sync_markdown_file | Create or replace a page from a local Markdown file |

> Tool parameters are defined in src/server.js.

---

Configuration

Configured entirely through environment variables:

| Variable | Required | Description |
|---|---|---|
| NOTION_TOKEN_V2 | ✅ | Your Notion session cookie (token_v2) |
| NOTION_PRIVATE_API_BASE | — | API base URL (default: https://www.notion.so) |

Getting your token_v2

1. Log in to Notion in your browser: <https://www.notion.so>
2. Open DevTools (F12) → Application → Cookies → https://www.notion.so
3. Copy the value of the token_v2 cookie.

> 🔒 Treat it like a password. Keep it in your shell env or an untracked .env — never commit it.

cp .env.example .env   # then edit .env

---

Usage with MCP clients

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "notion-private": {
      "command": "node",
      "args": ["/absolute/path/to/notion-private-api-mcp/src/server.js"],
      "env": { "NOTION_TOKEN_V2": "your_token_v2" }
    }
  }
}

Claude Code

claude mcp add notion-private \
  --scope local \
  --env NOTION_TOKEN_V2='your_token_v2' \
  -- node /absolute/path/to/notion-private-api-mcp/src/server.js

The helper scripts ./run-desktop.sh and ./run-codex.sh resolve the repo path automatically
and log to /tmp.

---

Example prompts

Once connected, just talk to your agent:

- "Find my 'Q3 Roadmap' page in Notion and summarize it."
- "Create a child page under <page> titled 'Meeting notes' with today's action items."
- "Append a TODO list to <page> with these three tasks…"
- "Sync my local CHANGELOG.md into the release-notes page."

---

Writing content

Tools that write accept a plain-JSON simplified block format:

[
  { "type": "heading_1", "text": "Release Notes" },
  { "type": "paragraph", "text": "First paragraph." },
  { "type": "to_do", "text": "Ship the feature", "checked": true },
  { "type": "toggle", "text": "Details", "children": [
    { "type": "bulleted_list_item", "text": "Item one" }
  ]}
]

Supported types: paragraph, heading_1/2/3, bulleted_list_item, numbered_list_item,
to_do, toggle, quote, callout, code, divider.

You can also pass Markdown (a stable subset: headings, paragraphs, bullet/numbered lists,
task items, blockquotes, fenced code, horizontal rules). Call get_style_documentation from your
client for the authoritative, machine-readable catalog. Nested lists, tables and inline formatting
are not implemented yet.

---

Troubleshooting / FAQ

Where do I get token_v2? See Getting your token_v2.

NOTION_TOKEN_V2 is required — the env var isn't set in the process that launches the server
(check your MCP client's env block, not just your shell).

My token stopped working — token_v2 expires when your Notion session ends (logout, password
change, long inactivity). Grab a fresh cookie and update it.

MemcachedCrossCellError — a transient Notion routing error on multi-cell workspaces. The
client already retries and falls back to loadPageChunk; just retry the call if it surfaces.

Is this against Notion's ToS? It uses an undocumented internal API. Use only with your own
account and data, at your own risk.

---

Project layout

src/
├── server.js         # MCP server: tool registration + stdio transport
├── notion-client.js  # Private-API client (cookie auth, transactions, retries)
├── notion-blocks.js  # Builds Notion block trees from simplified blocks
├── markdown.js       # Markdown → simplified-block parser
└── style-docs.js     # Catalog returned by get_style_documentation

---

Contributing

Issues and PRs are welcome. If this saved you time, please ⭐ the repo — it genuinely helps others
discover it.

---

License

MIT © kir.vigen

Disclaimer

Not affiliated with Notion Labs, Inc. Relies on an undocumented internal API; by using it you
accept all risks, including possible account restrictions and breakage when the API changes.
Use only with your own data.