Notion Workspace Operations

notion

Search, read, and edit Notion pages, databases, and data sources via the official Notion MCP server.

Installs: 4.4k
Namespace: notion
Version: >=2.0.0 <3.0.0
Last attach: reviewed1 months ago

Add to your mcp.json

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

Open in VS CodeDon't have it? Install FrootAI for VS Code

Attach in a FrootAI play (fai-manifest)

mcp_scope:
  attached:
    - notion

Authentication

integration-token

create an internal integration at notion.so/profile/integrations, share the target pages/databases with it (Access tab), then set NOTION_TOKEN to the integration secret (`ntn_…`); OPENAPI_MCP_HEADERS is an advanced header-based alternative.

Required credential: NOTION_TOKEN

Environment variables

Variable	Required	Auth mode	Description
NOTION_TOKEN	yes	integration-token	Notion internal-integration secret (`ntn_…`). Issue from notion.so/profile/integrations; it scopes which pages and databases the server can reach. Pass via env, never inline in args (doctrine #6).
OPENAPI_MCP_HEADERS	no	integration-token	Advanced alternative to NOTION_TOKEN: a JSON string of HTTP headers (e.g. an Authorization bearer plus a Notion-Version header). Use either NOTION_TOKEN or this; pass via env, never inline in args (doctrine #6).

Sample tools

notion.query-data-source
Query a Notion data source (database) with filters and sorts (uses `data_source_id`).
notion.retrieve-a-data-source
Get the schema and metadata for a data source.
notion.retrieve-a-database
Get database metadata, including its data-source IDs.
notion.retrieve-page-markdown
Read a page's full content as token-efficient Markdown.
notion.update-page-markdown
Edit a page's content with Markdown (`replace_content` or targeted `update_content`).
notion.move-page
Move a page to a different parent page or data source.

Used in recipes

FAI cookbook recipes that attach notion.

Destructive-action audit

1 destructive tool — confirm per call

Each runs only when the trust policy allows it; under allowDestructive: false they prompt per call.

notion.delete-a-block

Destructive-action audit (X2.18): block deletion (`delete-a-block`) is flagged in `destructive_tools`; the Notion integration scope excludes database deletion, and the trust policy sets `allowDestructive: false` (per-call confirm, X1.6 evidence).

Known limitations

Requires a Notion internal-integration token (NOTION_TOKEN); without it the server attaches but every Notion API tool returns an auth error.
Tools only see pages and databases explicitly shared with the integration — connect each target via the integration's Access tab first, or tools return empty / not-found.
v2.0+ migrated databases to the data-source model (Notion API 2025-09-03): database operations use `data_source_id`, and the legacy create/update/query `*-a-database` tools were removed.

Spec contributors

Maintainers who landed commits onmcp-specs/notion.json.

pspsbali

Freshness

When this spec was last reviewed by a maintainer and last machine-validated against the live server.

Spec last reviewed: 1 months ago(2026-06-25)
Auto-validated: never