notion-guest-mcp

An MCP server that lets AI assistants read Notion with a guest account, using Notion's internal API through the token_v2 session cookie.

⚠️ This uses an undocumented API. It can break at any time and may be against Notion's Terms of Service. token_v2 gives full access to your Notion account, so treat it like a password and never commit it.

Setup

Get token_v2: open Notion in the browser → F12 → Application (Storage in Firefox) → Cookies → the Notion domain → copy the value of token_v2.

Get root page URLs: copy the links of the pages under "Shared" in the sidebar (••• → Copy link).

Claude Code

claude mcp add mcp_notion --scope user \
  -e NOTION_TOKEN_V2=<token_v2> \
  -e NOTION_ROOT_PAGES="<url 1>,<url 2>" \
  -- npx -y notion-guest-mcp

Codex

codex mcp add mcp_notion \
  --env NOTION_TOKEN_V2=<token_v2> \
  --env NOTION_ROOT_PAGES="<url 1>,<url 2>" \
  -- npx -y notion-guest-mcp

Or add it to ~/.codex/config.toml:

[mcp_servers.mcp_notion]
command = "npx"
args = ["-y", "notion-guest-mcp"]
env = { NOTION_TOKEN_V2 = "<token_v2>", NOTION_ROOT_PAGES = "<url 1>,<url 2>" }

JSON config

For clients configured with an mcpServers JSON file (Claude Desktop, Cursor, ...):

{
  "mcpServers": {
    "mcp_notion": {
      "command": "npx",
      "args": ["-y", "notion-guest-mcp"],
      "env": {
        "NOTION_TOKEN_V2": "<token_v2>",
        "NOTION_ROOT_PAGES": "<url 1>,<url 2>"
      }
    }
  }
}

With all of the above, the token is stored in plain text in the client's config file.

Tools

| Tool | Description | |---|---| | search | Search pages under an ancestor page (ancestor, defaults to every page in NOTION_ROOT_PAGES) | | get_page | Get a page or database as markdown, including breadcrumb, properties and comment threads. Child pages, child databases, rows and relations are rendered as links /<page_id>; files as notion-file:<block_id> | | get_file | Download a Notion-hosted file (image, video, PDF, comment attachment) to a temp folder. Images are also returned inline so the AI can see them |

All tools are read-only for now.

Configuration

Values are read from environment variables, or from .env in the project root when running from source. Environment variables take precedence.

| Variable | Required | Description | |---|---|---| | NOTION_TOKEN_V2 | ✅ | Notion session cookie. Get it from DevTools → Application → Cookies → token_v2 | | NOTION_ROOT_PAGES | | URLs of your root pages (the "Shared" section in the sidebar), comma separated. search looks in all of them by default |

Troubleshooting

| Symptom | Fix | |---|---| | NOTION_TOKEN_V2 is required | The variable is not set, or .env is missing or empty | | invalid url in NOTION_ROOT_PAGES | One of the URLs has no page ID. Copy the link again from Notion | | Requests fail with 401 | The token expired (logging out ends the session). Copy a fresh token_v2 | | search returns nothing | The page you are looking for is not under any root in NOTION_ROOT_PAGES | | Old behavior after an update | npx may reuse a cached version. Use notion-guest-mcp@latest |