MCP Notion Server Files

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:

:::bash
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.