Notion MCP Server

tl;dr: the official local server is makenotion/notion-mcp-server (npm: @notionhq/notion-mcp-server, 4.6k stars, 109,953 weekly downloads). 22 tools, MIT, stdIO or streamable HTTP. Notion has also launched a remote Notion MCP at https://mcp.notion.com/mcp (OAuth) — the README explicitly says they may sunset the local repo. Use the remote one for new agents if your client supports it.

Status of the local server

The makenotion/notion-mcp-server README leads with a note: “We’ve introduced Notion MCP, a remote MCP server … We are prioritizing, and only providing active support for, Notion MCP (remote). As a result: we may sunset this local MCP server repository in the future.”

For the local package specifically: v2.0.0 was a breaking release (Notion API 2025-09-03 introduces “data sources” as the primary abstraction; the server migrated all DB ops accordingly). Current: v2.5.1.

Install (local)

npx -y @notionhq/notion-mcp-server

Claude Desktop config (NOTION_TOKEN)

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

Generate the integration at notion.so/profile/integrations (internal). Share the pages/databases you want the agent to see from the Access tab of the integration. For a read-only scope, give the integration only “Read content” in the Configuration tab.

Install (remote Notion MCP — preferred for new agents)

The remote server is documented at developers.notion.com/docs/mcp. It uses OAuth and does not require you to mint or paste a token.

{
  "mcpServers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

Tools (22 in v2.x; was 19 in v1.x)

Highlights, after the 2025-09-03 data-sources migration:

• query-data-source — replaces post-database-query
• retrieve-a-data-source / update-a-data-source / create-a-data-source
• list-data-source-templates
• retrieve-a-database — still returns database metadata, including data source IDs
• search / retrieve-page / create-page / update-page / move-page
• retrieve-page-markdown / update-page-markdown — page content as Markdown (uses Notion-Version 2026-03-11 per tool)
• create-a-comment

The full tool list: the npm README and the in-repo src directory.

v2.0.0 breaking changes (skim before upgrading)

• data_source_id replaces database_id for queries / updates / creates.
• Search filter values changed from ["page", "database"] to ["page", "data_source"].
• retrieve-a-database still exists; use it to list the data source IDs, then retrieve-a-data-source for schema.
• 3 tools removed, 7 added, total 22.

If you have hard-coded tool names from a v1.x prompt or workflow, search-and-replace database → data_source in the right places.

Transport

• stdio (default): npx @notionhq/notion-mcp-server
• streamable HTTP: npx @notionhq/notion-mcp-server --transport http --port 3000 (bearer token required; --unsafe-disable-auth exists for isolated dev networks only)

Streamable HTTP also supports per-request Notion tokens via the Notion-Token header (start with --enable-token-passthrough) so one deployment can serve many integrations.

Gotchas

• The integration is scoped by what you share with it. By default, it sees nothing — you have to add pages in the integration’s Access tab.
• Page deletion isn’t exposed (the team explicitly removed it for safety).
• The local repo’s GitHub issues are not actively monitored. File remote-MCP issues through Notion support instead.

Related

• Google Drive MCP — Drive + Docs (Anthropic reference is archived)
• Jira MCP — for Atlassian workspaces
• Slack MCP — messaging
• MCP Servers Explained