Notion MCP Server

About

The Notion MCP Server is the official integration from Notion that connects AI assistants directly to your Notion workspace via the Notion REST API. With 4,580+ GitHub stars, it is the canonical MCP tool for bringing Notion's knowledge management capabilities into Claude Desktop, Cursor, Windsurf, and any MCP-compatible client. The server exposes a rich set of tools: search your entire workspace by keyword and return matching pages and databases; retrieve full page content and block trees; create new pages inside any parent page or workspace section; update, append, or delete block content on existing pages; list all databases your integration has access to; query database entries with filter and sort parameters; retrieve individual blocks or nested children by block ID; and add comments to pages. Authentication uses a Notion integration token — create an internal integration at notion.so/my-integrations, share specific pages or databases with it, and set NOTION_TOKEN in your environment (the older OPENAPI_MCP_HEADERS form still works). Install with a single npx command. The Notion MCP Server is especially powerful for AI workflows that span documentation retrieval, project planning, and knowledge capture — Claude can read product specs from Notion, draft new pages from conversation output, log structured data into databases, and search across thousands of notes without any manual copy-paste.

Installation

npx -y @notionhq/notion-mcp-server

Setting up Notion MCP

1. 1.Option A — connect the hosted server (recommended)

   Nothing to install. In Claude Code, add the remote endpoint and complete the OAuth flow with /mcp. Cursor takes the same URL as a `url` entry in mcp.json, VS Code as an http-type server in .vscode/mcp.json, and Claude Desktop and ChatGPT both take it under Settings → Connectors → Add Connector.

   shell

   claude mcp add --transport http notion https://mcp.notion.com/mcp

2. 2.Option B — create an internal integration (local server only)

   The local server authenticates with an integration token, not OAuth. Create an internal integration at notion.so/profile/integrations. If you only want the assistant to read, grant just "Read content" under Capabilities — that is the cleanest way to bound the blast radius, since the token is what an LLM will be holding.

3. 3.Share the pages you want reachable

   A fresh integration can see nothing. Open the integration's Access tab and select the pages and databases to expose, or go to a page → ⋯ → Connect to integration. Access is inherited, so sharing a parent page covers its children. This step is where most "the search tool returns nothing" reports end.

4. 4.Point your client at the local server

   Add the server to claude_desktop_config.json or .cursor/mcp.json with the token in NOTION_TOKEN. The older OPENAPI_MCP_HEADERS form still works and is what you need if you want to pin the Notion-Version header yourself, but NOTION_TOKEN is the documented recommendation.

   claude_desktop_config.json

   {
     "mcpServers": {
       "notionApi": {
         "command": "npx",
         "args": ["-y", "@notionhq/notion-mcp-server"],
         "env": { "NOTION_TOKEN": "ntn_****" }
       }
     }
   }

What changed in v2.0 of the local server

v2.0.0 moved to the 2025-09-03 Notion API, where a database is addressed through its data sources. Three tools were removed and seven added — 22 total, up from 19. No config change is needed (clients re-discover tools on start), but hardcoded tool names in your prompts will break.

What people use it for

Which one should you use?

Categories

Works With

Frequently Asked Questions

Related Guides