Notion Private API MCP

What kirvigen/notion-private-api-mcp MCP server does

The kirvigen/notion-private-api-mcp MCP server provides read and write operations for a Notion workspace through Notion's private API. It can inspect page metadata and individual blocks, retrieve direct children, create child pages, append content, replace page contents, update block text, and archive direct child blocks. A separate tool can create or replace a page from a local Markdown file.

The server uses Notion permissions associated with the supplied browser session, so it can operate on pages visible to that account rather than only pages explicitly shared with an integration. It is an unofficial implementation and is not affiliated with Notion.

How it works

The process runs as an MCP server over stdio using the official MCP SDK. The client launches the Node.js server and passes configuration through environment variables. Requests are sent to Notion's internal API at the configured base URL, with the token_v2 browser cookie used for authentication.

Writing tools accept either simplified block JSON or Markdown. Supported simplified blocks include paragraphs, three heading levels, bulleted and numbered list items, to-do items, toggles, quotes, callouts, code, and dividers. The Markdown parser handles headings, paragraphs, ordinary and task lists, blockquotes, fenced code, and horizontal rules. Nested lists, tables, and inline formatting are not implemented. get_style_documentation returns the machine-readable catalog of supported block types and annotations, while markdown_to_blocks lets a client inspect Markdown conversion before writing.

Setup and configuration

To run the kirvigen/notion-private-api-mcp MCP server, clone the repository, install its Node.js dependencies, set the required environment variable, and start the process with npm start. The project requires Node.js 18 or newer.

NOTION_TOKEN_V2 must contain the token_v2 cookie from an authenticated Notion browser session. It should be kept like a password: use a shell environment or an untracked .env file, and do not commit it. NOTION_PRIVATE_API_BASE is optional and defaults to https://www.notion.so; it can change the private API base URL.

Claude Desktop configuration supplies the server command and token in its MCP configuration. The README also documents Claude Code usage and includes helper scripts for desktop and Codex launches.

Tools and capabilities

• Read a page and its metadata with get_page.
• Inspect a block or its direct children with get_block and get_block_children.
• Create child pages from blocks or Markdown.
• Append or replace page content, including insertion after a specified block.
• Replace plain text in a block, such as a code block.
• Archive direct child blocks.
• Preview Markdown parsing and consult supported style documentation.
• Synchronize a local Markdown file into a new or existing page.

Limitations and notes

The kirvigen/notion-private-api-mcp MCP server depends on Notion's undocumented internal API, including the /api/v3 endpoint. Notion may change or disable that interface, and the server may stop working without notice. The session cookie can expire after logout, a password change, or extended inactivity, requiring a new value.

Because the cookie effectively grants account-level access, use the server only with your own account and data and protect the credential carefully. The README warns that private API use may conflict with Notion's Terms of Service and is not intended for production or multi-tenant applications. Transient MemcachedCrossCellError responses may require retrying the operation.