Notion MCP Server

Official Notion MCP server for searching content, querying databases/data sources, and creating, updating, and moving pages in Notion workspaces.

Collaboration by Notion OAuth2 active

Connect (Remote Server) GitHub Docs npm: @notionhq/notion-mcp-server

Overview

Notion MCP is the official Model Context Protocol server from Notion that lets AI assistants read from and write to a Notion workspace. It is offered as a remote, hosted server at https://mcp.notion.com/mcp that uses OAuth, and as a self-hosted Node.js/Docker server (@notionhq/notion-mcp-server) that authenticates with an internal integration token. Notion recommends the remote server for most users, since it handles auth via OAuth and is actively maintained.

The server exposes around 22 tools that map onto the Notion API 2025-09-03, which treats data sources (the typed schemas behind databases) as the primary abstraction. Capabilities include searching pages, querying and updating data sources, retrieving and updating databases and pages, creating new pages and data sources, moving pages between parents, working with comments, and listing data source templates.

Because it ships from the makenotion GitHub organization and the notionhq npm scope, it is the canonical way to wire AI agents (Claude Desktop, Claude Code, Cursor, VS Code Copilot, ChatGPT) into a Notion workspace without writing custom API glue.

Tools

Tool	Description
`search`	Search across pages and data sources in the connected workspace.
`query-data-source`	Query a Notion data source with filters and sorts.
`retrieve-a-data-source`	Retrieve metadata and schema for a data source.
`create-a-data-source`	Create a new data source under a database parent.
`update-a-data-source`	Update properties (schema) of an existing data source.
`list-data-source-templates`	List the templates available for a data source.
`retrieve-a-database`	Retrieve metadata for a database including its data source IDs.
`create-a-page`	Create a new page with a page_id or database_id parent.
`retrieve-a-page`	Fetch a page and its properties.
`update-page-properties`	Update properties on an existing page.
`move-page`	Relocate a page to a different parent.
`retrieve-block-children`	Fetch the block children for a page or block.
`append-block-children`	Append new blocks to a page or block.
`create-comment`	Create a comment on a page or discussion thread.
`retrieve-comments`	Retrieve comments on a block or page.
`list-users`	List users in the workspace.
`retrieve-a-user`	Retrieve a single user by ID.

Setup Guide

Option 1: Remote server (recommended)

Notion hosts the MCP server at https://mcp.notion.com/mcp over Streamable HTTP, with OAuth-based auth. No tokens to manage.

Claude Desktop / Claude.ai: Settings → Connectors → Add Connector, paste the URL, then complete OAuth.

Cursor: Cursor Settings → MCP → Add new global MCP server.

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

VS Code (GitHub Copilot): create .vscode/mcp.json with the same config, then run "MCP: List Servers" and start Notion. Complete OAuth in the browser when prompted.

Option 2: Self-hosted (npm)

Useful when you need to bind to a specific Notion integration or run inside your own infra. The repo is at github.com/makenotion/notion-mcp-server (note: Notion has stated this local server may be sunset in favor of the remote one).

Create an internal integration at https://notion.so/profile/integrations and copy the secret (it starts with ntn_).
In your Notion workspace, share the relevant pages or databases with the integration.
Add the server to your MCP client config:

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

Option 3: Self-hosted (Docker)

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "NOTION_TOKEN", "mcp/notion"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

For HTTP transport on the local server:

npx @notionhq/notion-mcp-server --transport http --port 3000

The local HTTP endpoint listens at http://0.0.0.0:<port>/mcp and requires a bearer token.

Use Cases

Pull weekly status updates from a Notion "Projects" database and summarize them into a digest page
Have an agent triage a "Bugs" data source: filter by severity, update statuses, and assign owners
Create new meeting-notes pages from a calendar event, with linked tasks back to the team's task database
Search across the workspace for any mention of a customer or feature and stitch together a briefing doc
Keep a roadmap data source in sync with engineering plans by appending blocks and updating properties from a coding agent

Example Prompts

"Search Notion for any page mentioning 'Q3 launch plan' and summarize the top 5 results."
"Query the 'Tasks' database for items where Status is 'In progress' and Owner is me, then list them by due date."
"Create a new page in the 'Meeting notes' database titled 'Weekly sync, May 14' with agenda, attendees, and action items sections."
"Add a comment on the 'Pricing v2' page asking the doc owner to confirm the launch date."
"Move the page 'Onboarding checklist' under the 'People Ops' parent page."

Pros

Official, maintained by Notion; remote server uses OAuth so there are no tokens to rotate
Covers the core Notion API surface: search, data sources, databases, pages, blocks, comments, users
Multiple deployment options: hosted URL, npm, or Docker image
v2 aligns with the 2025-09-03 API and exposes data sources as a first-class concept

Limitations

The local server repo may be sunset in favor of the remote server; issues and PRs are not actively monitored
Self-hosted mode requires manually sharing each page/database with the integration in Notion's UI, which is easy to forget
Large workspaces can hit Notion API rate limits during broad searches or bulk updates

Alternatives

suekou/mcp-notion-server: community Notion MCP server
awkoy/notion-mcp-server: community implementation with an alternative tool layout
Native Notion API via a generic OpenAPI MCP server, if you need custom tool shapes