Notion Documentation

Use this skill when Notion is the system of record for specs, runbooks, project tracking, or knowledge management.

Current MCP Reality

As of March 2026, Notion documents two supported ways to use its MCP server:

Hosted remote MCP endpoint: https://mcp.notion.com/mcp
Local stdio server package: @notionhq/notion-mcp-server

Hosted mode uses OAuth. Local mode uses an internal integration token. Official docs also list supported tools for searching content, reading pages, comments, users, and working with pages and databases.

Activation Conditions

Creating or updating Notion pages
Building project trackers or engineering knowledge bases
Organizing specs, ADRs, and onboarding docs in Notion
Adding review comments or using database-backed workflows

Practical Workflow

Confirm whether the client exposes the hosted Notion MCP server or a local stdio connection.
Read or search existing pages before creating duplicates.
Use databases for tracked work and pages for long-form documents.
Keep properties simple: owner, status, last reviewed, tags.
If MCP is unavailable in the current client, fall back to local content prep using the included script and templates.

Operational Notes

Official Notion guidance currently documents an average rate limit of 20 requests per second for integrations.
Tool names can vary slightly by MCP host, but the supported capabilities are stable: search, fetch page content, create or update pages, create or update databases, manage comments, and read user context.

References & Resources

Documentation

Notion Markdown Spec - Notion-flavored Markdown constraints and conversion notes
Database Properties - Practical property patterns for docs and project trackers
Notion MCP Quickstart - Hosted endpoint, local package, auth options, and usage notes

Scripts

Notion Templates - Local page and database template helpers for environments without Notion MCP access

Examples

Workspace Setup Example - Example team workspace structure using pages, databases, and review comments

Related Skills

Skill	Relationship
notebooklm-management	Alternative research and knowledge workflow
documentation-authoring	Create source docs before publishing them into Notion

notion-docs