Skip to content

suekou/mcp-notion-server

v2.0.0 Breaking

This release includes 4 breaking changes for platform teams planning a safe upgrade.

Published 1mo MCP SaaS Integrations
✓ No known CVEs patched
Read the diff → Tool health → What is this tool? →

✓ No known CVEs patched in this version

Topics

mcp model-context-protocol notion notion-api npm typescript

Affected surfaces

breaking_upgrade deps

Summary

AI summary

Node.js 22+ is now required and pnpm replaces npm as the supported package manager.

Full changelog

Release Notes

v2.0.0

This major release modernizes @suekou/mcp-notion-server for the latest Notion API and introduces a more AI-friendly MCP tool surface designed for practical agent workflows.

Highlights

  • Updated Notion API support to 2026-03-11.
  • Migrated database-oriented workflows toward the new Notion Data Sources API.
  • Added high-level AI-friendly tools for search, page reading, data source inspection, schema-aware querying, simple item creation, and content editing.
  • Added Markdown append support for converting a safe Markdown subset into Notion blocks.
  • Improved response handling with compact response modes, structured content, and tool errors that agents can self-correct from.
  • Replaced node-fetch with native Node.js fetch, including timeout, retry, Retry-After, and structured Notion API error handling.
  • Migrated the project from npm to pnpm.
  • Updated runtime support to Node.js 22+.
  • Added Biome-based linting and formatting.
  • Added CI and publish workflows.
  • Added React-based MCP apps for data source exploration and page workbench workflows.
  • Expanded documentation for setup, configuration, tools, and recommended workflows.

New AI-Friendly Tools

  • notion_find
  • notion_read_page
  • notion_inspect_data_source
  • notion_query_data_source_by_values
  • notion_create_data_source_item_from_values
  • notion_append_content
  • notion_append_markdown
  • notion_update_content
  • notion_update_content_batch

Notion API Changes

  • Uses Notion-Version: 2026-03-11.
  • Adds first-class support for data sources.
  • Keeps notion_retrieve_database for discovering child data_source_id values from database containers.
  • Updates append block children behavior to use position.
  • Prefers in_trash over legacy archived fields where applicable.
  • Adds Markdown conversion support for data_source responses.

Breaking Changes

  • Node.js 22 or newer is now required.
  • pnpm is now the supported package manager.
  • Database-centric workflows should move to data source tools.
  • Some tool arguments and response shapes have changed to align with the latest Notion API and MCP SDK patterns.

Migration Notes

Install with a Node.js 22+ runtime and use pnpm for local development:

pnpm install
pnpm run build
pnpm test

For AI-agent workflows, prefer the new high-level tools first:

  1. notion_find
  2. notion_read_page or notion_inspect_data_source
  3. notion_append_markdown, notion_append_content, notion_update_content, or data source value-based tools
  4. Use low-level block/page/data source tools only for advanced shapes not covered by the high-level tools.

Breaking Changes

  • Minimum Node.js version raised to 22+.
  • pnpm is now the required package manager (replaces npm).
  • Database-centric workflows must migrate to data source tools.
  • Tool arguments and response shapes have changed for alignment with Notion API and MCP SDK patterns.
View diff on GitHub

Weekly OSS security release digest.

The CVE patches and breaking changes that affected production tools this week. One email, every Sunday.

No spam, unsubscribe anytime.

Share this release

Share on X Share on Bluesky

Track suekou/mcp-notion-server

Get notified when new releases ship.

Sign up free

About suekou/mcp-notion-server

Interacting with Notion API

All releases →

Related context

Beta — feedback welcome: [email protected]