kirvigen/notion-private-api-mcp

> **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
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) |