Notion MCP server

Last verified: 2026-09

Search and update Notion pages.

Community Chat, mail & docs Needs a secret Claude Desktop, Cursor, Windsurf, Claude Code

What it does

Notion's official MCP (@notionhq/notion-mcp-server). v2 changed page content to markdown and renamed some tools. Search, read, and update pages and data sources the integration can see.

It sits in Chat, mail & docs: These servers act as the bot or the integration you install.

Good for

Search pages the integration was invited to — not the whole workspace.
Read a page as markdown (v2) and turn it into a PR description.
Update a spec page after you reviewed the diff.
Query a database/data source that is already the team's tracker.

Tools

search — Find pages and databases the integration was invited to.
retrieve / create / update pages — Markdown body in v2.
data source / database query — Structured tables. Check the current names after the v2 rename.

Config (Claude Desktop / Cursor / Windsurf)

Paste the JSON below. Same mcpServers shape. Replace placeholder paths and secrets. Windows paths look like C:\\Users\\you\\project, not /path/to. Host-side steps →

Claude Desktop

OS	Config file
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json` (usually `C:\Users\<you>\AppData\Roaming\Claude\`)
Linux	`~/.config/Claude/claude_desktop_config.json`

Cursor

Scope	macOS / Linux	Windows
This project	`.cursor/mcp.json` in the repo root
This user	`~/.cursor/mcp.json`	`%USERPROFILE%\.cursor\mcp.json`

Windsurf

OS	Config file
macOS / Linux	`~/.codeium/windsurf/mcp_config.json`
Windows	`%USERPROFILE%\.codeium\windsurf\mcp_config.json`

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

Windsurf remote MCP: use serverUrl instead of url if the block below is HTTP.

One-liner: npx -y @notionhq/notion-mcp-server

Secrets it wants: NOTION_TOKEN

Source repo →

How to get started

Create a Notion internal integration. Invite it to specific pages only.
Set NOTION_TOKEN. Restart and search for one page title.
If a tool name 404s, you are on v1 docs — read the v2 breaking-change note.

Access risk

An integration invited to the workspace root can read everything. Invite per page.

When to skip it

Skip it for a local vault (Obsidian) or for Jira/Linear tickets.

Instead: Obsidian, Confluence, Linear.

Files & knowledgeObsidianRead and search a local Obsidian vault. Chat, mail & docsConfluenceRead Confluence pages. Chat, mail & docsLinearIssues, projects, and cycles in Linear.

Vs alternatives

Server	Official?	Needs a secret?	Best for
Notion	No	Yes	Search and update Notion pages.
Obsidian	No	Yes	Read and search a local Obsidian vault.
Confluence	No	Yes	Read Confluence pages.
Linear	No	Yes	Issues, projects, and cycles in Linear.

More in Chat, mail & docs

OfficialGoogle MapsGeocode and place search via Google Maps. OfficialSlackRead channels and post messages. Chat, mail & docsAsanaTasks and projects in Asana. Chat, mail & docsConfluenceRead Confluence pages.

All 18 in this category →

FAQ

Why did a tool name 404?

v2.0 breaking change: page content is markdown and some tools were renamed. Read Notion's v2 note.

How do I limit what it sees?

Create an internal integration and invite it to specific pages. Do not add it to the workspace root.

Notion or Obsidian?

Notion if the team already lives there. Obsidian for a local vault.

Official?

Yes — @notionhq/notion-mcp-server.