Notion MCP Server

Project

Author: suekou
Repository: github.com/suekou/mcp-notion-server
Website: www.npmjs.com/package/@suekou/mcp-notion-server
License: MIT
Category: Memory & Knowledge

Tech

Runtime / language: node
Transports: stdio
Remote available: No
Authentication: Not specified

Activity

GitHub stars: 920
Last commit: Jul 31, 2026
Data as of: Oct 16, 2026

Overview

Notion MCP Server gives agents an interface to Notion workspace content using the current database and data source model. The README targets Notion API version 2026-03-11 and emphasizes compact results for everyday assistant workflows. Discovery begins with notion_find, followed by page reading that returns stable block identifiers and bounded content. Data source inspection summarizes schema before querying or creating items. Simplified value-based helpers handle common filters, sorts, and property values without requiring the agent to construct raw Notion JSON. These features support a deliberate progression from finding the target to understanding its structure and then making changes.

Page editing includes common content types such as paragraphs, headings, lists, todos, quotes, callouts, and code blocks. Safe Markdown append and batch content updates cover routine changes, while lower-level tools remain available for blocks, pages, databases, data sources, comments, and users. Optional Data Source Explorer and Page Workbench apps provide interactive workflows. Setup uses an internal Notion integration token and explicit sharing of accessible pages or databases. Capabilities must match the requested operations, with separate permissions for reading, insertion, updates, and comments. The supplied tool data notes Enterprise and Organization API key requirements for specific user lookups. Client configuration launches the npm package through npx; development uses Node.js 22 or newer and pnpm. The project is MIT-licensed.

Install & configure

Requirements

npx
An MCP host
A Notion internal integration token
Content shared with the integration and appropriate capabilities

Documented launch / install command

npx -y @suekou/mcp-notion-server

Restart the MCP host after configuration. Grant only needed capabilities and share target pages or databases with the integration. Development prerequisites specify Node.js 22 or newer and pnpm.

Claude Desktop

Cursor

VS Code

Windsurf

Claude Code

Config file · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Use Settings → Developer → Edit Config when available. Do not assume a Linux configuration path; check the client documentation for your platform. Remote servers use the app’s connector flow when supported, not the local stdio file shown here. Merge this example with existing settings; do not overwrite unrelated servers.

Claude Desktop configuration

{
  "mcpServers": {
    "mcp-notion-server": {
      "command": "npx",
      "args": [
        "-y",
        "@suekou/mcp-notion-server"
      ],
      "env": {
        "NOTION_API_TOKEN": "<Notion internal integration token>"
      }
    }
  }
}

Read the Claude Desktop setup guide

Config file · Project: .cursor/mcp.json

User: ~/.cursor/mcp.json

The project path is relative to the workspace root. The tilde denotes your user home directory. Use Cursor’s MCP settings to confirm which configuration and scope your installed version is reading. Merge this example with existing settings; do not overwrite unrelated servers.

Cursor configuration

{
  "mcpServers": {
    "mcp-notion-server": {
      "command": "npx",
      "args": [
        "-y",
        "@suekou/mcp-notion-server"
      ],
      "env": {
        "NOTION_API_TOKEN": "<Notion internal integration token>"
      }
    }
  }
}

Read the Cursor setup guide

Config file · Workspace: .vscode/mcp.json

For user scope, use the “MCP: Open User Configuration” command if available. Do not guess a user configuration path across operating systems, profiles, containers, or remote workspaces; check the client documentation. Merge this example with existing settings; do not overwrite unrelated servers.

VS Code configuration

{
  "servers": {
    "mcp-notion-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@suekou/mcp-notion-server"
      ],
      "env": {
        "NOTION_API_TOKEN": "<Notion internal integration token>"
      }
    }
  }
}

Read the VS Code setup guide

Config file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json

Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

Open the MCP configuration through Windsurf’s settings when possible to confirm the active file. Paths can differ in managed or future releases; check the client documentation if this location is not present. Merge this example with existing settings; do not overwrite unrelated servers.

Windsurf configuration

{
  "mcpServers": {
    "mcp-notion-server": {
      "command": "npx",
      "args": [
        "-y",
        "@suekou/mcp-notion-server"
      ],
      "env": {
        "NOTION_API_TOKEN": "<Notion internal integration token>"
      }
    }
  }
}

Read the Windsurf setup guide

Config file · Project scope: .mcp.json at the repository root

The project file uses mcpServers. For user scope, use claude mcp add --scope user rather than assuming .mcp.json in your home directory is the user configuration. Check the client documentation for managed settings and storage details. Merge this example with existing settings; do not overwrite unrelated servers.

Claude Code configuration

{
  "mcpServers": {
    "mcp-notion-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@suekou/mcp-notion-server"
      ],
      "env": {
        "NOTION_API_TOKEN": "<Notion internal integration token>"
      }
    }
  }
}

Read the Claude Code setup guide

Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.

Tools

Source: repository tool metadata. Tool descriptions are a documented snapshot, not a live capability check.

Tool	What it does
notion_open_data_source_app	Open an interactive app for schema inspection, filtering, queries, and item creation.
notion_open_page_workbench	Open an interactive app for page reading, block selection, simple edits, and Markdown append.
notion_append_block_children	Insert child blocks beneath a parent at a specified position.
notion_append_content	Append common content types without constructing raw block JSON.
notion_append_markdown	Append supported Markdown elements as Notion blocks.
notion_update_content	Replace simple content fields on an existing block of the matching type.
notion_update_content_batch	Validate target block types and apply several simple content updates.
notion_retrieve_block	Fetch a single Notion block.
notion_retrieve_block_children	Fetch blocks nested beneath a parent.
notion_delete_block	Remove a selected Notion block.
notion_update_block	Replace selected block fields using the raw API shape.
notion_retrieve_page	Fetch page metadata from Notion.
notion_read_page	Read bounded page content as an outline or Markdown with block identifiers.
notion_update_page_properties	Change properties on a page or database item.
notion_list_all_users	List workspace users; the tool data notes Enterprise and Organization API key requirements.
notion_retrieve_user	Fetch a user by ID; the tool data notes Enterprise and Organization API key requirements.
notion_retrieve_bot_user	Inspect the bot identity associated with the token.
notion_retrieve_database	Inspect a database container and discover its child data sources.
notion_create_database	Create a database and its initial data source schema.
notion_create_data_source	Add another data source to an existing database.
notion_query_data_source	Query a data source with filters, ordering, and pagination.
notion_query_data_source_by_values	Query using schema-aware simple filters and sort values.
notion_retrieve_data_source	Fetch data source metadata and property definitions.
notion_update_data_source	Change a data source title, description, or schema.
notion_create_data_source_item	Create a page item using a data source as parent.
notion_create_data_source_item_from_values	Create an item by converting simple values against the data source schema.
notion_create_comment	Add a comment to a page or discussion with the required integration capability.
notion_retrieve_comments	Read unresolved comments with the required comment capability.
notion_find	Discover candidate pages or data sources with compact results and suggested follow-up tools.
notion_inspect_data_source	Summarize schema properties, options, and relation targets for an agent.
notion_search	Search for pages or data sources by title.

Names, permissions, and defaults can change. Check the current upstream documentation before granting access.

Use cases

Locate pages and read compact content with stable block IDs
Query Notion data sources using schema-aware filters
Append Markdown or batch-edit common page blocks
Create data source items from simple property values
Use interactive Notion exploration and editing apps

Strengths

Provides simplified helpers alongside low-level API tools
Bounds page reads to limit response size
Includes optional interactive MCP Apps
Uses schema inspection before common data source operations

Limitations

Only shared content and granted capabilities are accessible
Some user lookup tools require Enterprise and an Organization API key
Markdown append supports a limited safe subset

Frequently asked questions

No. Notion content must be shared with the integration; page access also extends to its children.

The README specifies 2026-03-11 and the database/data source model.

No. Simplified content, Markdown, and value-based tools cover common operations; raw API tools handle advanced shapes.

Optional MCP Apps include Data Source Explorer and Page Workbench.

Independent listing, not an affiliation or security review. Grant the least access needed and verify the upstream instructions before running code.

Server facts

Project

Tech

Activity

Tags

Overview

Install & configure

Requirements

Tools

Use cases

Strengths

Limitations

Frequently asked questions

Related MCP servers

MCP Knowledge Graph

Context7

MCP Server for Obsidian