Notion MCP Server

Project

Author: makenotion
Repository: github.com/makenotion/notion-mcp-server
License: MIT
Category: Memory & Knowledge

Tech

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

Activity

GitHub stars: 4,668
Last commit: Sep 20, 2026
Data as of: Oct 16, 2026

Overview

Notion MCP Server connects compatible AI clients to the Notion API, exposing operations for workspace pages, databases, and data sources. Its database model follows the API migration that made data sources the main unit for querying and schema changes. The README identifies tools for filtered queries, metadata retrieval, template discovery, and moving pages. It also describes reading and editing page content as Markdown, which avoids requiring agents to manipulate block JSON for those tasks. Different operations receive their required Notion API version automatically unless a custom header overrides that behavior.

Setup starts with an internal Notion integration and an explicit choice of which pages and databases it can access. Capabilities can be narrowed to reading content when write access is unnecessary. The package can run through npm or Docker, with standard input/output as the default connection method. Streamable HTTP is also available and normally requires bearer authentication; per-connection Notion token passthrough can serve multiple integrations. The main caveat is project status: Notion says its remote MCP service receives active support, while this local repository may eventually be retired and its issues and pull requests are not actively watched. Existing users should also review renamed database tools when upgrading.

Install & configure

Requirements

A Notion internal integration
Access granted to the relevant pages or databases
An MCP-compatible client
npx for the npm launch method

Documented launch / install command

npx -y @notionhq/notion-mcp-server

This configuration launches the local stdio server. HTTP and Docker alternatives are documented. Notion prioritizes support for its separate remote service.

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": {
    "notion-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@notionhq/notion-mcp-server"
      ],
      "env": {
        "NOTION_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": {
    "notion-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@notionhq/notion-mcp-server"
      ],
      "env": {
        "NOTION_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": {
    "notion-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@notionhq/notion-mcp-server"
      ],
      "env": {
        "NOTION_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": {
    "notion-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@notionhq/notion-mcp-server"
      ],
      "env": {
        "NOTION_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": {
    "notion-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@notionhq/notion-mcp-server"
      ],
      "env": {
        "NOTION_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 README. Tool descriptions are a documented snapshot, not a live capability check.

Tool	What it does
query-data-source	Search a data source using filters and sort rules.
retrieve-a-data-source	Read a data source schema and metadata.
update-a-data-source	Change properties belonging to a data source.
create-a-data-source	Add a new data source.
list-data-source-templates	Find templates available within a data source.
move-page	Relocate a page beneath another parent.
retrieve-a-database	Read database metadata and associated data source identifiers.
retrieve-page-markdown	Fetch page content as Markdown, optionally including meeting transcripts.
update-page-markdown	Replace page Markdown or apply targeted text changes.

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

Use cases

Query Notion data sources with filters and sorting.
Read page content as Markdown for an AI workflow.
Update page text or move a page to another parent.
Inspect database metadata and data source schemas.

Strengths

Offers Markdown reading and editing alongside data source operations.
Supports scoped integration capabilities and explicit page access.
Provides stdio, HTTP, and Docker deployment choices.

Limitations

The local repository no longer receives active issue and pull request monitoring.
Upgrading can require changes to hardcoded database tool names.

Frequently asked questions

No. The README distinguishes this local repository from Notion MCP remote, which receives active support.

Yes. Configure the integration capabilities to allow reading content and grant access only to the desired pages.

Version 2.0 replaces older database operations with data source tools, including query-data-source and its data_source_id parameter.

Yes. The README describes retrieve-page-markdown and update-page-markdown for page content operations.

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

Server facts