# kirvigen/notion-private-api-mcp [Health: Active]

**Category:** 🛠️ Other Tools and Integrations  
**Repository:** https://github.com/kirvigen/notion-private-api-mcp  
**GitHub Stars:** 4  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/kirvigen-notion-private-api-mcp

## Description
Unofficial Notion server via the private API (tokenv2): full read/write across your entire workspace with no integration token and no per-page sharing.

## Tools
Capabilities this server exposes over MCP:

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

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "notion-private-api-mcp": {
    "command": "npx",
    "args": ["-y","kirvigen-notion-private-api-mcp"],
    "env": {
      "NOTION_TOKEN_V2": ""
    }
  }
}
```

**Requires environment variables:** `NOTION_TOKEN_V2` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/kirvigen-notion-private-api-mcp/readme_