Log inSubmit server
Notion MCP logo

Notion MCP

Search, export, edit, create, and comment on Notion pages through markdown-focused MCP tools.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Notion MCP

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "notion-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@shck-dev/notion-mcp"
      ],
      "env": {
        "NOTION_TOKEN": "YOUR_VALUE_HERE",
        "NOTION_USER_ID": "YOUR_VALUE_HERE",
        "NOTION_SPACE_ID": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

Install not yet sandbox-tested— we haven't run this command through our automated sandbox yet. Not a red flag; we're working through the catalog.

Overview

The notion-mcp MCP server connects AI clients to the Notion workspace visible in your browser, using Notion's internal API rather than the official integration API. It supports workspace search, markdown export and import, append operations, child-page creation, image handling, and discussion comments. Setup uses credentials copied from a Notion browser request, either through an interactive initializer or environment variables. Reach for it when an agent needs broad page access and bidirectional markdown workflows, while accepting internal-API and token-expiry limitations.

Use cases

  • Search a workspace for pages matching a query
  • Export Notion pages into markdown files
  • Replace or append page content from markdown
  • Create child pages from local documentation
  • Review and reply to open Notion discussions

Key features

  • Full-text workspace search
  • Markdown page export and import
  • Non-destructive markdown append
  • Child-page creation from text or files
  • Image upload and URL references
  • Notion discussion comments

Tools13

What Notion MCP lets your agent do. Expand a tool for its parameters.

Self-reported~275 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 2d ago

Recent health check succeeded.

7/7 checks healthy over the last 46d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 10d ago via OSV.dev · @shck-dev/notion-mcp (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars2Stargazers on the source repository.
npm downloads182Package downloads in the last 30 days.
Last commit4mo agoMost recent push to the default branch.
Tools exposed13Callable tools this server registers over MCP.

How Notion MCP works

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:

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

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Notion MCP

notion-mcp is an MCP server that connects AI clients to a Notion workspace through the web app’s internal API. Its main tools search pages, export and import markdown, append content, create child pages, add images, and list, start, or reply to discussion comments using browser-derived credentials.

Run `npx @shck-dev/notion-mcp init`, paste a cURL request copied from Notion’s browser developer tools, and register the resulting server with your MCP client. Node.js 18 or newer is required for `npx`; Bun is also supported.

Set `NOTION_TOKEN`, `NOTION_USER_ID`, and `NOTION_SPACE_ID`, or let `notion_init` extract them from a browser request. The values come from the `token_v2` cookie, an active-user request header, and the request payload’s `spaceId`.

Yes, notion-mcp works with Cursor through its MCP configuration. Add the package as a server command and provide the three Notion environment variables, unless you used the initializer to save credentials locally.

Yes, the import tools replace all existing page content. Use `notion_append_to_page` or its file variant when the requirement is to add markdown at the end without removing the current content.

Related MCP servers

All in Workplace & Productivity All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewNotion MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/notion-mcp?style=directory)](https://allmcps.com/mcp/notion-mcp)
HTML Embed
<a href="https://allmcps.com/mcp/notion-mcp"><img src="https://allmcps.com/api/badge/notion-mcp?style=directory" alt="Notion MCP on AllMCPs" /></a>