What for: let AI read and edit your Notion pages and databases in Markdown, right inside your workspace, without leaving the chat.

What it gives the AI

The AI treats your Notion as a knowledge base: it searches the workspace, reads pages and databases, creates and edits content (in Markdown), and fills in record properties. Handy for turning notes into tasks, pulling together summaries, and populating databases without leaving the chat.

Example: "Turn the meeting notes on page X into a task list in the Tasks database with deadlines" — the AI reads the page and creates records with the fields filled in.

Setup (exact steps)

Two paths: the hosted remote server with OAuth (simpler) or self-hosted via npx with an internal token.

Claude Code

Recommended — the remote server (OAuth, no manual tokens):

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

Then /mcp → sign in to Notion in the browser.

Self-hosted with an internal integration token:

claude mcp add notion --env NOTION_TOKEN=ntn_YOUR_TOKEN -- npx -y @notionhq/notion-mcp-server

Cursor / Claude Desktop

The self-hosted npx option:

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

The remote option is the same block with "type": "http" and "url": "https://mcp.notion.com/mcp".

Usage example

Say: "Find every page in Notion about onboarding and merge them into one summary" → the AI searches the workspace, reads what it finds and creates a summary page. Or "add a record to the CRM database for this new lead".

Security

Least access: for a self-hosted token, create an internal integration (notion.so/profile/integrations) and share only the pages/databases it needs via the Access tab or "Connect to integration". The integration sees exactly what's been shared with it.
OAuth for remote: more convenient and with no permanent token; permissions are revoked in /mcp.
Don't commit the ntn_... token to a repository — keep it in env vars or a local scope.

Gotchas

Common mistake: the integration is created but the pages are not shared with it — the AI "can't see" the content. Check Access.
Writes are real: the AI can change or overwrite a page. On important databases, limit the integration to read-level content access.
Large databases and long pages hit the MCP output limit — ask for selections and filters rather than "dump everything".

Notion MCP