# notion-mcp [Health: Active]

**Category:** 🏢 Workplace & Productivity  
**Repository:** https://github.com/shck-dev/notion-mcp  
**GitHub Stars:** 2  
**npm Downloads (last month):** 182  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/notion-mcp

## Description
Notion MCP server — search, export, and import pages as markdown

## Tools
Capabilities this server exposes over MCP:

- **notion_search** — Full-text search across all pages in your workspace
- **notion_export_page** — Export any Notion page as markdown; image links resolve to viewable CDN URLs (pass `image_dir` to download images locally instead)
- **notion_import_page** — Write markdown to a Notion page — **replaces** all existing content
- **notion_import_page_from_file** — Write a local `.md` file to a page — **replaces** all content
- **notion_append_to_page** — Append markdown to the **end** of a page (non-destructive)
- **notion_append_to_page_from_file** — Append a local `.md` file to the end of a page (non-destructive)
- **notion_create_page** — Create a new sub-page, optionally prefilled with markdown
- **notion_create_page_from_file** — Create a new sub-page from a local `.md` file
- **notion_add_image** — Append an image to the end of a page — local file is uploaded to Notion, http(s) URL is referenced as-is
- **notion_list_comments** — List open discussion threads on a page
- **notion_add_comment** — Start a new discussion — inline (anchored to text) or block-level
- **notion_reply_comment** — Reply to an existing discussion thread
- **notion_init** — Paste a browser "Copy as cURL" to extract & save credentials

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "notion-mcp": {
    "command": "npx",
    "args": ["-y","@shck-dev/notion-mcp"],
    "env": {
      "NOTION_TOKEN": "",
      "NOTION_USER_ID": "",
      "NOTION_SPACE_ID": ""
    }
  }
}
```

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

## Documentation

## What notion-mcp does

The notion-mcp MCP server gives an MCP client tools for finding and changing content in a Notion workspace. Search covers pages across the workspace, while export converts a page into markdown with headings, lists, tasks, code blocks, tables, links, and image references. Exported image links resolve to viewable CDN URLs; an image directory can be supplied when local downloads are preferred.

Markdown can be written to an existing page from a string or local `.md` file. These import operations replace the page's existing content. Append tools provide a non-destructive alternative by adding markdown to the end. The server can also create child pages, optionally populated from markdown, append a local image or external image URL, and work with open discussion threads through listing, creation, and reply tools.

## How it works

The notion-mcp MCP server uses the same undocumented internal API used by the Notion web application. Authentication is based on a browser cookie and workspace-specific identifiers, rather than OAuth or an integration token. Access follows what the authenticated Notion user can see in the browser, so the server does not require separately sharing each page.

The server runs as a Node-compatible package through `npx`, with Node.js 18 or newer required. Bun is also supported. MCP clients invoke the listed tools over the server process; the package additionally provides a setup prompt and a `notion://guide` resource for in-client onboarding.

## Setup and configuration

The quickest setup is:

```bash
npx @shck-dev/notion-mcp init
```

The initializer accepts a browser Network request copied as cURL from a request to Notion's `api/v3` endpoint. It extracts the credentials and saves them to `~/.notion-mcp/config.json`. The server can then be registered without an environment block.

For manual configuration, provide these values:

- `NOTION_TOKEN`: the `token_v2` cookie from `www.notion.so`
- `NOTION_USER_ID`: the `x-notion-active-user-header` request-header value
- `NOTION_SPACE_ID`: the `spaceId` found in the request payload

Keep credentials private because they are taken from an authenticated browser session.

## Tools and capabilities

Available operations include:

- Search every page in the workspace.
- Export pages to markdown and optionally download images locally.
- Replace page content from markdown text or a local file.
- Append markdown without replacing existing content.
- Create child pages from text or files.
- Add local images or reference HTTP(S) image URLs.
- List open discussions, start inline or block-level comments, and reply to threads.
- Extract and save credentials with `notion_init`.

## Limitations and notes

The notion-mcp MCP server depends on an undocumented Notion API that may change. The `token_v2` credential expires periodically, so authentication failures may require copying fresh browser credentials.

Database or collection pages do not export their rows. Sub-pages render as links, and pages of that type may return an explanatory note rather than empty output. Import replaces all content, while append only adds at the end; neither operation edits individual blocks in place. Markdown conversion can simplify complex formatting, including flattening some nested lists. External image URLs are referenced as provided rather than uploaded to Notion.

The project is licensed under MIT.

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