Notion

v1.0.088 callsOAuthGitHub

Documentation

Guide

Your Notion workspace, fully accessible through AI.

A Model Context Protocol (MCP) server that exposes Notion's API for managing pages, databases, blocks, and users across your workspace.

Overview

The Notion MCP Server provides a complete interface to your Notion workspace:

Search, read, and write pages with full block-level content control
Create and query databases with filters, sorts, and pagination
Manage workspace users and bot identity

Perfect for:

AI assistants that need to read or update Notion pages and databases
Automating content creation, knowledge base updates, and task management
Building tools that integrate Notion with other services

Tools

Read Operations

Searches all pages and databases by title, or lists all workspace content when no query is provided.

Inputs:

- `query` (string, optional) — Search query string; leave empty to list all pages (default: "")
- `filter_type` (string, optional) — Filter results by type: page or data_source
- `page_size` (int, optional) — Number of results to return (max: 100, default: 20)
- `start_cursor` (string, optional) — Pagination cursor from a previous response

output:

{
  "results": [{ "id": "page-id", "object": "page", "properties": {...} }, ...],
  "next_cursor": "cursor-string",
  "has_more": true
}

Retrieves a Notion page with its properties and metadata.

Inputs:

- `page_id` (string, required) — The Notion page ID

output:

{
  "id": "page-id",
  "object": "page",
  "properties": { "title": { "title": [{ "plain_text": "Page Title" }] } },
  "parent": { "type"

Retrieves a Notion page along with all its child blocks. Supports recursive fetching up to a configurable depth.

Inputs:

- `page_id` (string, required) — The Notion page ID
- `include_children` (bool, optional) — Fetch child blocks (default: true)
- `recursive` (bool, optional) — Recursively fetch nested blocks (default: false)
- `max_depth` (int, optional) — Maximum nesting depth for recursive fetch (default: 3)
- `page_size` (int, optional) — Number of blocks per page (default: 100)
- `start_cursor` (string, optional) — Pagination cursor for blocks

output:

Write Operations

Creates a new child page under an existing parent page.

Inputs:

- `parent_page_id` (string, required) — ID of the parent page
- `title` (string, optional) — Title of the new page (default: "Untitled New page Created")
- `position` (object, optional) — Insert position: {"type": "page_end"} or {"type": "page_start"}

output:

{
  "id": "new-page-id"

Creates a new page at the workspace level, not under any parent page.

Inputs:

- `title` (string, optional) — Title of the new page (default: "Untitled New page Created")

output:

{
  "id": "new-page-id",
  "object": "page",
  "url": "https://www.notion.so/new-page-id",
  ...
}

Updates properties, icon, cover, archive status, or lock state of an existing page.

Inputs:

- `page_id` (string, required) — The Notion page ID
- `properties` (object, optional) — Page properties to update (schema depends on page type)
- `icon` (object, optional) — Page icon (emoji or external URL)
- `cover` (object, optional) — Page cover image (external URL)
- `archived` (bool, optional) — Archive or unarchive the page
- `in_trash` (bool, optional) — Move to trash or restore from trash
- `is_locked` (bool, optional) — Lock or unlock the page
- `template` (object, optional) — Template settings
- `erase_content` (bool, optional) — Erase all page content

output:

Adds a text block (paragraph, heading, list item, etc.) to an existing page or block.

Inputs:

- `block_id` (string, required) — Page ID or parent block ID to append to
- `type` (string, required) — Block type: paragraph, heading_1, heading_2, heading_3, bulleted_list_item, numbered_list_item, to_do, toggle, quote, or callout
- `content` (string, required) — Text content for the block
- `checked` (bool, optional) — For to_do blocks only — whether the item is checked
- `color` (string, optional) — Text or background color (e.g., red, blue_background)
- `position` (string, optional) — Insertion position: start or end

output:

Database Operations

Retrieves a Notion database object with its title, parent, and data sources.

Inputs:

- `database_id` (string, required) — The Notion database ID

output:

{
  "id": "database-id",
  "title": [{ "plain_text": "My Database" }],
  "properties": {...},
  ...
}

Retrieves the schema and properties of a database (data source) by ID.

Inputs:

- `data_source_id` (string, required) — The data source (database) ID

output:

{
  "id": "database-id",
  "properties": {
    "Name": { "type": "title" },
    "Status": { "type": "select", "select": {

Queries a database to retrieve pages matching optional filters and sort criteria.

Inputs:

- `data_source_id` (string, required) — The data source (database) ID to query
- `filter` (object, optional) — Notion filter object to narrow results
- `sorts` (list, optional) — List of sort objects to order results
- `page_size` (int, optional) — Number of results per page (max: 100, default: 100)
- `start_cursor` (string, optional) — Pagination cursor from a previous response

output:

{
  "results": [{

Creates a new database as a child of an existing page, with optional properties, icon, and cover.

Inputs:

- `parent_id` (string, required) — ID of the parent page to create the database under
- `title` (string, optional) — Database title (default: "Untitled Database")
- `description` (string, optional) — Database description
- `properties` (object, optional) — Database property schema definition
- `is_inline` (bool, optional) — Create as inline database (default: false)
- `icon` (object, optional) — Database icon (emoji or external URL)
- `cover` (object, optional) — Database cover image

output:

User Operations

Lists all users in the workspace. Guest users are excluded.

Inputs:

- `page_size` (int, optional) — Number of users per page (max: 100, default: 100)
- `start_cursor` (string, optional) — Pagination cursor from a previous response

output:

{
  "results": [{ "id": "user-id", "name": "Jane Doe", "type": "person",

Returns information about a specific workspace user by their ID.

Inputs:

- `user_id` (string, required) — The Notion user ID

output:

{
  "id": "user-id",
  "name": "Jane Doe",
  "type": "person",
  "person": { "email": "jane@example.com" }
}

Returns information about the bot associated with the current API token, including owner and workspace details.

Inputs:

none

output:

{
  "id": "bot-user-id",
  "name": "My Integration",
  "type": "bot",
  "bot": { "owner": { "type": "workspace" }, "workspace_name"

API Parameters Reference

Notion IDs are UUIDs and can be found in the page URL:

https://www.notion.so/workspace/my-page-<page-id>
Example page_id: 8f9b3c2d-1a2b-3c4d-5e6f-7a8b9c0d1e2f

dashes are optional — both formats work with the API.

Troubleshooting

Resources

Notion API Documentation — Official API reference
Notion API Reference — Complete endpoint reference
FastMCP Docs — FastMCP specification
FastMCP Credentials — FastMCP Credentials package for credential handling

Help Improve This Server

Missing a tool?

Found a bug?

Have an idea for an improvement?

Share your feedback directly with the maintainers - every feedback helps make this server better for everyone.

Open GitHub Issues →