MCP Notion Server

https://github.com/suekou/mcp-notion-server
Admin
AI-friendly MCP server for the Notion API that helps agents find, read, query, and update Notion...
Tokens:42,633
Snippets:481
Trust Score:8.2
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install and test locally

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/00-overview.md

Commands for installing dependencies, building the project, and launching the inspector for local testing.

```bash
pnpm install
pnpm build
pnpm run inspector  # For local testing
```

--------------------------------

### Install Dependencies, Build, and Test

Source: https://github.com/suekou/mcp-notion-server/blob/main/README.md

Install project dependencies, build the project, and run tests using pnpm. Ensure you have Node.js 22+ and pnpm installed.

```bash
pnpm install --frozen-lockfile
pnpm run build
pnpm test
```

--------------------------------

### Get Server Instructions

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/01-mcp-server.md

Returns system instructions for the MCP server to guide tool usage.

```typescript
export function getServerInstructions(): string
```

--------------------------------

### Development commands

Source: https://github.com/suekou/mcp-notion-server/blob/main/docs/configuration.md

Commands for installing dependencies, building the project, running tests, and starting the inspector during development.

```bash
pnpm install --frozen-lockfile
pnpm run build
pnpm test
pnpm run inspector
```

--------------------------------

### startServer(notionToken, enabledToolsSet, enableMarkdownConversion)

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/01-mcp-server.md

Initializes and starts the MCP server with stdio transport.

```APIDOC
## startServer

### Description
Initializes and starts the MCP server with stdio transport.

### Parameters
- **notionToken** (string) - Required - Notion API integration token for authentication
- **enabledToolsSet** (Set<string>) - Required - Set of tool names to enable; empty set enables all tools
- **enableMarkdownConversion** (boolean) - Required - Whether to convert Notion responses to Markdown format

### Returns
- **Promise<void>**
```

--------------------------------

### Example Invocation of notion_append_page_content

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/09-prompts-resources.md

A JSON example showing how to invoke the notion_append_page_content prompt with required arguments.

```json
{
  "name": "notion_append_page_content",
  "arguments": {
    "page": "Project Status",
    "content": "## Meeting Notes from 2026-08-04\n\n- Discussed Q4 goals\n- Assigned action items"
  }
}
```

--------------------------------

### getServerInstructions()

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/01-mcp-server.md

Returns system instructions for the MCP server that guide tool usage.

```APIDOC
## getServerInstructions

### Description
Returns system instructions for the MCP server that guide tool usage.

### Returns
- **string**
```

--------------------------------

### Start the MCP Server

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/01-mcp-server.md

Initializes and starts the MCP server using stdio transport. Requires a valid Notion API token.

```typescript
export async function startServer(
  notionToken: string,
  enabledToolsSet: Set<string>,
  enableMarkdownConversion: boolean,
): Promise<void>
```

```typescript
import { startServer } from './mcp/server.js';

const token = process.env.NOTION_API_TOKEN;
const enabledTools = new Set(['notion_find', 'notion_read_page']);
const enableMarkdown = process.env.NOTION_MARKDOWN_CONVERSION === 'true';

await startServer(token, enabledTools, enableMarkdown);
```

--------------------------------

### Example Query Usage

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/06-data-source-tools.md

Demonstrates a typical query request including filters, sorting, and pagination settings.

```json
{
  "data_source_id": "12345678-1234-1234-1234-123456789012",
  "filters": [
    {
      "property": "Status",
      "operator": "equals",
      "value": "In Progress"
    },
    {
      "property": "Due Date",
      "operator": "before",
      "value": "2026-12-31"
    }
  ],
  "match": "all",
  "sorts": [
    {
      "property": "Due Date",
      "direction": "ascending"
    }
  ],
  "page_size": 20
}
```

--------------------------------

### Rich Text Object Example

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/11-schema-parameters.md

Example array containing text, linked text with annotations, and a user mention object.

```json
[
  {
    "type": "text",
    "text": {
      "content": "Hello "
    }
  },
  {
    "type": "text",
    "text": {
      "content": "world",
      "link": { "url": "https://example.com" }
    },
    "annotations": {
      "bold": true
    }
  },
  {
    "type": "mention",
    "mention": {
      "type": "user",
      "user": {
        "object": "user",
        "id": "12345678-1234-1234-1234-123456789012"
      }
    }
  }
]
```

--------------------------------

### Usage Example for renderMarkdownBlockTree

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/14-markdown-conversion.md

Demonstrates how to render a page's outline into Markdown.

```typescript
const pageRead = await readPage(pageId, { content_format: 'json' });
const markdown = renderMarkdownBlockTree(pageRead.content.outline);
```

--------------------------------

### notion_create_data_source_item_workflow Invocation

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/09-prompts-resources.md

Example JSON invocation for the notion_create_data_source_item_workflow prompt.

```json
{
  "name": "notion_create_data_source_item_workflow",
  "arguments": {
    "data_source": "Tasks",
    "item": "Create a task with title 'Review PR', status 'To Do', and due date next Monday"
  }
}
```

--------------------------------

### Append Content Example

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/05-content-tools.md

Example payload for the notion_append_content tool, demonstrating various content types and positioning.

```json
{
  "block_id": "12345678-1234-1234-1234-123456789012",
  "items": [
    {
      "type": "heading_1",
      "text": "Project Goals"
    },
    {
      "type": "paragraph",
      "text": "This quarter we aim to..."
    },
    {
      "type": "bulleted_list_item",
      "text": "Improve performance"
    },
    {
      "type": "bulleted_list_item",
      "text": "Add new features"
    },
    {
      "type": "code",
      "text": "function hello() {\n  console.log('world');\n}",
      "language": "javascript"
    }
  ],
  "position": {
    "type": "after_block",
    "after_block": {
      "id": "existing-block-id-here"
    }
  }
}
```

--------------------------------

### Example usage of notion_open_page_workbench

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/08-app-tools.md

Provides an initial page ID to load into the Page Workbench.

```json
{
  "page_id": "12345678-1234-1234-1234-123456789012"
}
```

--------------------------------

### notion_query_data_source_items_workflow Invocation

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/09-prompts-resources.md

Example JSON invocation for the notion_query_data_source_items_workflow prompt.

```json
{
  "name": "notion_query_data_source_items_workflow",
  "arguments": {
    "data_source": "Tasks",
    "query": "Find all tasks with status In Progress due before next Friday"
  }
}
```

--------------------------------

### Parent Object Configurations

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/11-schema-parameters.md

JSON examples for defining different parent types when creating new content or databases.

```json
{
  "type": "page_id",
  "page_id": "12345678-1234-1234-1234-123456789012"
}
```

```json
{
  "type": "database_id",
  "database_id": "12345678-1234-1234-1234-123456789012"
}
```

```json
{
  "type": "data_source_id",
  "data_source_id": "12345678-1234-1234-1234-123456789012"
}
```

```json
{
  "type": "workspace"
}
```

--------------------------------

### Example Usage of notion_create_database

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/06-data-source-tools.md

Demonstrates a complete request payload for creating a 'My Tasks' database with title, status, and date properties.

```json
{
  "parent": {
    "type": "page_id",
    "page_id": "12345678-1234-1234-1234-123456789012"
  },
  "title": [
    {
      "type": "text",
      "text": { "content": "My Tasks" }
    }
  ],
  "initial_data_source": {
    "properties": {
      "Name": {
        "type": "title"
      },
      "Status": {
        "type": "status",
        "status": {
          "options": [
            { "name": "To Do" },
            { "name": "In Progress" },
            { "name": "Done" }
          ]
        }
      },
      "Due Date": {
        "type": "date"
      }
    }
  }
}
```

--------------------------------

### Example usage of notion_open_data_source_app

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/08-app-tools.md

Provides an initial data source ID to load into the Data Source Explorer.

```json
{
  "data_source_id": "12345678-1234-1234-1234-123456789012"
}
```

--------------------------------

### Example Usage of notion_create_comment

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/03-discovery-tools.md

Example payload for creating a comment on a page using the parent object and rich text content.

```json
{
  "parent": {
    "page_id": "12345678-1234-1234-1234-123456789012"
  },
  "rich_text": [
    {
      "type": "text",
      "text": {
        "content": "Great progress on this task!"
      }
    }
  ]
}
```

--------------------------------

### Execute Notion search query

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/03-discovery-tools.md

Example usage of the notion_search tool to find data sources matching a query.

```json
{
  "query": "expenses",
  "filter": {
    "property": "object",
    "value": "data_source"
  },
  "page_size": 10
}
```

--------------------------------

### Usage of renderBlockToMarkdown

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/14-markdown-conversion.md

Example demonstrating how to render a single block with metadata enabled.

```typescript
const block = await client.retrieveBlock(blockId);
const markdown = renderBlockToMarkdown(block, { includeBlockMetadata: true });
```

--------------------------------

### notion_find_target Invocation

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/09-prompts-resources.md

Example JSON invocation for the notion_find_target prompt.

```json
{
  "name": "notion_find_target",
  "arguments": {
    "target": "Project roadmap"
  }
}
```

--------------------------------

### Render Database Schema as Markdown Table

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/14-markdown-conversion.md

Example of how database properties and schemas are represented in Markdown format.

```markdown
# Database Name

**Description:** Database description

## Properties

| Property | Type | Details |
|----------|------|---------|
| Name | title | — |
| Status | status | Options: To Do, In Progress, Done |
| Priority | select | Options: Low, Medium, High |
| Due Date | date | Date range allowed: No |
| Tags | multi_select | Options: UI, Backend, Docs |
```

--------------------------------

### Usage of notion_read_page

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/04-page-tools.md

Example input parameters for the notion_read_page tool to retrieve page content and metadata.

```json
{
  "page_id": "12345678-1234-1234-1234-123456789012",
  "content_format": "outline",
  "max_depth": 2,
  "max_blocks": 50
}
```

--------------------------------

### Update Notion Data Source Example

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/06-data-source-tools.md

Example JSON payload for updating a data source's title and description using the notion_update_data_source tool.

```json
{
  "data_source_id": "12345678-1234-1234-1234-123456789012",
  "title": [
    {
      "type": "text",
      "text": { "content": "Updated Data Source Title" }
    }
  ],
  "description": [
    {
      "type": "text",
      "text": { "content": "New description" }
    }
  ]
}
```

--------------------------------

### Usage of convertToMarkdown

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/14-markdown-conversion.md

Example demonstrating how to retrieve a page and convert its response to Markdown.

```typescript
import { convertToMarkdown } from './markdown/index.js';

const pageResponse = await client.retrievePage(pageId);
const markdown = await convertToMarkdown(pageResponse);
console.log(markdown);
```

--------------------------------

### Usage Example for renderRichTextToPlainText

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/14-markdown-conversion.md

Demonstrates extracting plain text from a paragraph.

```typescript
const plainText = renderRichTextToPlainText(paragraph.rich_text);
// Output: "Hello world" (without bold, italics, etc.)
```

--------------------------------

### Usage Example for renderRichTextToMarkdown

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/14-markdown-conversion.md

Demonstrates converting a paragraph's rich text into Markdown.

```typescript
const paragraph = block.paragraph;
const text = renderRichTextToMarkdown(paragraph.rich_text);
```

--------------------------------

### Configure Notion MCP Server with npm package

Source: https://github.com/suekou/mcp-notion-server/blob/main/README.md

Configure your MCP host to use the Notion MCP server installed via npm. This requires specifying the command, arguments, and your Notion integration token.

```json
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

--------------------------------

### Configure notion_read_page Request

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/14-markdown-conversion.md

Example JSON payload for requesting a page in markdown format with specific depth and block limits.

```json
{
  "page_id": "...",
  "content_format": "markdown",
  "max_depth": 3,
  "max_blocks": 200
}
```

--------------------------------

### notion_find_target Prompt Template

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/09-prompts-resources.md

Template used to guide the model in finding a Notion page or data source.

```text
Find a Notion page or data source

Find the Notion target for: {target}
Use `notion_find` first. Prefer `object_type` when the target kind is clear.
Return the best candidate ID, title, object type, and the suggested next tool.
If multiple candidates look plausible, ask the user to choose rather than guessing.
```

--------------------------------

### Example usage of notion_append_markdown

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/05-content-tools.md

Demonstrates the JSON structure required to call the notion_append_markdown tool with a block ID, Markdown content, and position.

```json
{
  "block_id": "12345678-1234-1234-1234-123456789012",
  "markdown": "# Meeting Notes\n\nKey points:\n- Action item 1\n- Action item 2\n\n```typescript\nfunction test() {}\n```",
  "position": {
    "type": "end"
  }
}
```

--------------------------------

### Retrieve Notion bot user

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/03-discovery-tools.md

Example usage of the notion_retrieve_bot_user tool to identify the integration user.

```json
{}
```

--------------------------------

### Example usage of notion_update_content_batch

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/05-content-tools.md

Updates multiple blocks simultaneously; validation occurs for all items before any changes are applied.

```json
{
  "updates": [
    {
      "block_id": "block-id-1",
      "item": {
        "type": "paragraph",
        "text": "First edit"
      }
    },
    {
      "block_id": "block-id-2",
      "item": {
        "type": "heading_2",
        "text": "Edited heading"
      }
    },
    {
      "block_id": "block-id-3",
      "item": {
        "type": "to_do",
        "text": "Check this off",
        "checked": true
      }
    }
  ]
}
```

--------------------------------

### Example Position Object

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/11-schema-parameters.md

JSON representation of a Position object configured to insert after a specific block ID.

```json
{
  "position": {
    "type": "after_block",
    "after_block": {
      "id": "12345678-1234-1234-1234-123456789012"
    }
  }
}
```

--------------------------------

### Example Usage of notion_append_block_children

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/07-block-tools.md

Demonstrates appending a paragraph with rich text and an external image block to a parent.

```json
{
  "block_id": "12345678-1234-1234-1234-123456789012",
  "children": [
    {
      "object": "block",
      "type": "paragraph",
      "paragraph": {
        "rich_text": [
          {
            "type": "text",
            "text": {
              "content": "A paragraph with "
            }
          },
          {
            "type": "text",
            "text": {
              "content": "bold text",
              "link": null
            },
            "annotations": {
              "bold": true
            }
          }
        ]
      }
    },
    {
      "object": "block",
      "type": "image",
      "image": {
        "type": "external",
        "external": {
          "url": "https://example.com/image.png"
        }
      }
    }
  ]
}
```

--------------------------------

### Example usage of notion_update_content

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/05-content-tools.md

Updates a single block by providing its ID and the new content item.

```json
{
  "block_id": "existing-block-id-from-read-page",
  "item": {
    "type": "paragraph",
    "text": "Updated paragraph text"
  }
}
```

--------------------------------

### Run MCP Inspector for Local Development

Source: https://github.com/suekou/mcp-notion-server/blob/main/README.md

Start the MCP inspector for local development. This tool aids in debugging and inspecting the server's behavior during development.

```bash
pnpm run inspector
```

--------------------------------

### Update a Notion block

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/07-block-tools.md

Example input for the notion_update_block tool, which replaces the entire value for specified fields.

```json
{
  "block_id": "12345678-1234-1234-1234-123456789012",
  "block": {
    "type": "paragraph",
    "paragraph": {
      "rich_text": [
        {
          "type": "text",
          "text": {
            "content": "Completely updated paragraph"
          }
        }
      ]
    }
  }
}
```

--------------------------------

### Read Notion Page with Outline Format

Source: https://github.com/suekou/mcp-notion-server/blob/main/docs/workflows.md

Use `notion_read_page` for most page reading tasks. Specify `content_format: "outline"` to get compact metadata and an outline with stable block IDs. Control the depth and number of blocks returned.

```json
{
  "page_id": "page-id",
  "content_format": "outline",
  "max_depth": 2,
  "max_blocks": 100
}
```

--------------------------------

### notion_append_page_content

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/09-prompts-resources.md

This prompt provides a guided workflow for appending or updating content on a Notion page, including instructions on which underlying tools to use based on the specific content requirements.

```APIDOC
## notion_append_page_content

### Description
Append or update readable Notion page content using simplified content tools. This prompt guides the user through a workflow to select the appropriate Notion tool for the task.

### Arguments
- **page** (string) - Required - The page title or ID.
- **content** (string) - Required - The content to append.

### Example Invocation
{
  "name": "notion_append_page_content",
  "arguments": {
    "page": "Project Status",
    "content": "## Meeting Notes from 2026-08-04\n\n- Discussed Q4 goals\n- Assigned action items"
  }
}
```

--------------------------------

### constructor(token: string, options?: NotionClientOptions)

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/02-notion-client.md

Initializes a new instance of the NotionClientWrapper with an API token and optional configuration.

```APIDOC
## constructor(token: string, options?: NotionClientOptions)

### Description
Creates a new Notion API client wrapper instance.

### Parameters
- **token** (string) - Required - Notion API integration token
- **options** (NotionClientOptions) - Optional - Configuration options (timeoutMs, maxRetries, retryDelayMs)
```

--------------------------------

### Run MCP Notion Server with CLI arguments

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/00-overview.md

Execute the server using npx with specific tools enabled via comma-separated values.

```bash
npx @suekou/mcp-notion-server --enabledTools notion_find,notion_read_page
```

--------------------------------

### Configure Local Development and Node.js Path

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/13-configuration.md

Configuration templates for running the server from a local build or specifying an explicit Node.js binary path.

```json
{
  "mcpServers": {
    "notion": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-notion-server/build/index.js"],
      "env": {
        "NOTION_API_TOKEN": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

```json
{
  "mcpServers": {
    "notion": {
      "command": "/usr/local/bin/node",
      "args": ["/path/to/mcp-notion-server/build/index.js"],
      "env": {
        "NOTION_API_TOKEN": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

--------------------------------

### getAllPrompts()

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/01-mcp-server.md

Returns the complete list of all available MCP prompts.

```APIDOC
## getAllPrompts

### Description
Returns the complete list of all available MCP prompts.

### Returns
- **Prompt[]** - Array of MCP Prompt definitions
```

--------------------------------

### Create Database

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/02-notion-client.md

Creates a new database instance with an initial data source based on the provided configuration object.

```typescript
async createDatabase(args: CreateDatabaseArgs): Promise<DatabaseResponse>
```

--------------------------------

### Perform Full Project Build

Source: https://github.com/suekou/mcp-notion-server/blob/main/docs/mcp-apps.md

Command to execute a full project build using pnpm. This includes building app assets and other project components.

```bash
pnpm run build
```

--------------------------------

### MCP Notion Server configuration using local build

Source: https://github.com/suekou/mcp-notion-server/blob/main/docs/configuration.md

Configure the MCP Notion Server to run from a local build. Provide the absolute path to the build index.js file and set the NOTION_API_TOKEN environment variable.

```json
{
  "mcpServers": {
    "notion": {
      "command": "node",
      "args": ["/absolute/path/to/suekou-mcp-notion-server/build/index.js"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token"
      }
    }
  }
}
```

--------------------------------

### notion_create_database

Source: https://github.com/suekou/mcp-notion-server/blob/main/docs/tools.md

Creates a new Notion database and its initial data source.

```APIDOC
## notion_create_database

### Description
Creates a new Notion database and its initial data source.

### Required Parameters
- **parent** (object) - The parent page or database where the new database will be created.
- **initial_data_source.properties** (object) - The initial schema for the data source, defining its properties.

### Optional Parameters
- **title** (string) - The title of the new database.
- **description** (string) - The description for the new database.
- **is_inline** (boolean) - Whether the database should be inline.
- **icon** (object) - An icon for the database.
- **cover** (object) - A cover image for the database.

### Note
With the current Notion API model, the initial schema goes under `initial_data_source.properties`.

### Request Example
```json
{
  "parent": {
    "type": "page_id",
    "page_id": "parent_page_id"
  },
  "title": "My New Database",
  "initial_data_source": {
    "properties": {
      "Name": {"type": "title"},
      "Status": {"type": "select", "options": ["To Do", "In Progress", "Done"]}
    }
  },
  "is_inline": false
}
```

### Response
#### Success Response (200)
- **database_id** (string) - The ID of the newly created database.

#### Response Example
```json
{
  "database_id": "newly_created_database_id"
}
```
```

--------------------------------

### Configure Notion MCP Server with Local Checkout

Source: https://github.com/suekou/mcp-notion-server/blob/main/README.md

Configure your MCP host to use a locally built Notion MCP server. This requires specifying the absolute path to the build index file and your Notion integration token.

```json
{
  "mcpServers": {
    "notion": {
      "command": "node",
      "args": ["/absolute/path/to/suekou-mcp-notion-server/build/index.js"],
      "env": {
        "NOTION_API_TOKEN": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

--------------------------------

### notion_create_data_source

Source: https://github.com/suekou/mcp-notion-server/blob/main/docs/tools.md

Add another data source to an existing database. Use `notion_create_database` when creating a new database.

```APIDOC
## notion_create_data_source

### Description
Add another data source to an existing database.

### Method
POST

### Endpoint
/notion/data_source/create

### Parameters
#### Request Body
- **parent** (object) - Required - The parent of the data source, e.g., `{ "type": "database_id", "database_id": "..." }`.
- **properties** (object) - Required - The properties of the data source.
- **title** (string) - Optional - The title of the data source.

### Request Example
{
  "parent": { "type": "database_id", "database_id": "..." },
  "properties": { ... },
  "title": "New Data Source"
}

### Response
#### Success Response (200)
- **data_source_id** (string) - The ID of the newly created data source.

#### Response Example
{
  "data_source_id": "..."
}
```

--------------------------------

### Create Notion data source item with simplified values

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/06-data-source-tools.md

The standard approach for creating items; the server validates property names and option values against the schema.

```json
{
  "data_source_id": "12345678-1234-1234-1234-123456789012",
  "values": {
    "Name": "New Task",
    "Status": "In Progress",
    "Priority": "High",
    "Due Date": "2026-12-25",
    "Tags": ["urgent", "project-alpha"],
    "Assigned": ["user-id-12345678901234567890123456789012"],
    "Done": false
  }
}
```

--------------------------------

### notion_create_data_source_item_workflow Prompt Template

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/09-prompts-resources.md

Template for the workflow to create a Notion data source item using schema inspection.

```text
Create a Notion data source item

Data source: {data_source}
Item request: {item}

Workflow:
1. Use `notion_find` with `object_type: "data_source"` if the data source ID is not already provided.
2. Use `notion_inspect_data_source` to get exact property names, option values, and relation fields.
3. Use `notion_create_data_source_item_from_values` with simple values whenever possible.
4. If a property type is unsupported by simple values, fall back to `notion_create_data_source_item` with raw Notion property JSON.
```

--------------------------------

### Handle NotionApiError in application code

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/12-errors.md

Example of catching and handling specific Notion API error statuses.

```typescript
import { NotionApiError } from './notion/errors.js';

try {
  await client.retrievePage(pageId);
} catch (error) {
  if (error instanceof NotionApiError) {
    if (error.status === 404) {
      console.error('Page not found. Check the page ID and sharing settings.');
    } else if (error.status === 403) {
      console.error('Permission denied. Grant integration capabilities in Notion.');
    } else if (error.status === 429) {
      console.log(`Rate limited. Retry after ${error.retryAfterMs}ms`);
    } else {
      console.error(`API error: ${error.code} - ${error.message}`);
    }
  } else {
    throw error;
  }
}
```

--------------------------------

### Configure Claude Desktop for Notion MCP

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/13-configuration.md

Standard configuration templates for the Claude Desktop application, including options for Markdown conversion and tool filtering.

```json
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

```json
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "NOTION_MARKDOWN_CONVERSION": "true"
      }
    }
  }
}
```

```json
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": [
        "-y",
        "@suekou/mcp-notion-server",
        "--enabledTools",
        "notion_find,notion_read_page,notion_append_content"
      ],
      "env": {
        "NOTION_API_TOKEN": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

--------------------------------

### Invalid Tool Name Error

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/12-errors.md

Returned when a requested tool does not exist.

```json
{
  "error": {
    "message": "Unknown tool: notion_invalid_tool_name"
  }
}
```

--------------------------------

### getAllTools()

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/01-mcp-server.md

Returns the complete list of all available MCP tools.

```APIDOC
## getAllTools

### Description
Returns the complete list of all available MCP tools.

### Returns
- **Tool[]** - Array of MCP Tool definitions
```

--------------------------------

### Handle Truncated Block Response

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/14-markdown-conversion.md

Example of a response object where children are omitted due to reaching the max_depth limit.

```typescript
{
  "id": "parent-block-id",
  "type": "paragraph",
  "text": "Parent content",
  "children": [
    {
      "id": "child-1",
      "type": "paragraph",
      "text": "Child 1",
      "children_omitted": "max_depth"  // Further children not fetched
    }
  ]
}
```

--------------------------------

### getAllResources()

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/01-mcp-server.md

Returns the complete list of all available MCP resources.

```APIDOC
## getAllResources

### Description
Returns the complete list of all available MCP resources (both Notion and app resources).

### Returns
- **Resource[]** - Array of MCP Resource definitions
```

--------------------------------

### Update Notion page properties

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/04-page-tools.md

Example payload for updating page or database item properties using the notion_update_page_properties tool.

```json
{
  "page_id": "12345678-1234-1234-1234-123456789012",
  "properties": {
    "Name": {
      "title": [
        {
          "type": "text",
          "text": { "content": "Updated Title" }
        }
      ]
    },
    "Status": {
      "status": {
        "name": "Done"
      }
    },
    "Due Date": {
      "date": {
        "start": "2026-12-31"
      }
    }
  }
}
```

--------------------------------

### createDatabase

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/02-notion-client.md

Creates a new database with an initial data source.

```APIDOC
## createDatabase

### Description
Creates a new database with an initial data source.

### Signature
`async createDatabase(args: CreateDatabaseArgs): Promise<DatabaseResponse>`

### Parameters
- **args** (CreateDatabaseArgs) - Required - Database configuration object

### CreateDatabaseArgs Fields
- **parent** (object) - Required - Parent page or workspace
- **initial_data_source** (object) - Required - Initial data source with properties
- **title** (RichTextItemResponse[]) - Optional - Database title
- **description** (RichTextItemResponse[]) - Optional - Database description
- **is_inline** (boolean) - Optional - Whether to display inline
- **icon** (object) - Optional - Database icon object
- **cover** (object) - Optional - Database cover object

### Returns
- **DatabaseResponse** - The created database object.
```

--------------------------------

### Define Initial Data Source Structure

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/06-data-source-tools.md

Defines the schema for the initial_data_source parameter, which dictates the properties of the new database.

```json
{
  "properties": {
    "Property Name": {
      "type": "string",
      // ... property schema ...
    },
    // ... more properties ...
  }
}
```

--------------------------------

### Enable Markdown Conversion

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/14-markdown-conversion.md

Set this environment variable to enable Markdown conversion for tool responses.

```bash
NOTION_MARKDOWN_CONVERSION=true
```

--------------------------------

### MCP Notion Server configuration with Markdown conversion enabled

Source: https://github.com/suekou/mcp-notion-server/blob/main/docs/configuration.md

Configure the MCP Notion Server with both the API token and the NOTION_MARKDOWN_CONVERSION environment variable set to 'true' for experimental Markdown conversion.

```json
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token",
        "NOTION_MARKDOWN_CONVERSION": "true"
      }
    }
  }
}
```

--------------------------------

### Create Data Source

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/02-notion-client.md

Initializes a new data source within an existing database using the provided properties and optional title.

```typescript
async createDataSource(
  parent: CreateDataSourceArgs["parent"],
  properties: NotionJsonObject,
  title?: RichTextItemResponse[],
): Promise<DataSourceResponse>
```

--------------------------------

### MCP Notion Server configuration using npx

Source: https://github.com/suekou/mcp-notion-server/blob/main/docs/configuration.md

Configure the MCP Notion Server to run via npx. Ensure the NOTION_API_TOKEN environment variable is set.

```json
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token"
      }
    }
  }
}
```

--------------------------------

### Create Notion data source item with raw properties

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/06-data-source-tools.md

Use this tool for property types not supported by the simplified value-based creation tool.

```json
{
  "data_source_id": "12345678-1234-1234-1234-123456789012",
  "properties": {
    "Name": {
      "title": [
        {
          "type": "text",
          "text": { "content": "New Item" }
        }
      ]
    },
    "Status": {
      "status": {
        "name": "To Do"
      }
    }
  }
}
```

--------------------------------

### getNotionPrompt(name, args)

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/09-prompts-resources.md

Retrieves a Notion prompt definition by name with optional arguments.

```APIDOC
## getNotionPrompt

### Description
Retrieves a prompt from the Notion server. Returns a GetPromptResult containing a description and an array of messages.

### Signature
`export function getNotionPrompt(name: string, args: Record<string, string> | undefined): GetPromptResult`

### Parameters
- **name** (string) - Required - The name of the prompt to retrieve.
- **args** (Record<string, string>) - Optional - A dictionary of arguments to pass to the prompt.
```

--------------------------------

### notion_query_data_source_items_workflow Prompt Template

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/09-prompts-resources.md

Template for the workflow to query Notion data source items using schema inspection.

```text
Query Notion data source items

Data source: {data_source}
Query: {query}

Workflow:
1. Use `notion_find` with `object_type: "data_source"` if the data source ID is not already provided.
2. Use `notion_inspect_data_source` to get exact property names, option values, and property types.
3. Use `notion_query_data_source_by_values` for common filters and sorts.
4. Fall back to `notion_query_data_source` only when the requested query needs raw Notion filter JSON.
```

--------------------------------

### Enable specific tools via CLI

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/13-configuration.md

Use this command to restrict the server to a specific subset of tools.

```bash
npx @suekou/mcp-notion-server --enabledTools notion_find,notion_read_page,notion_append_content
```

--------------------------------

### Initialize NotionClientWrapper

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/13-configuration.md

Configures the Notion client with custom timeout and retry parameters. Ensure NOTION_API_TOKEN is set in the environment variables.

```typescript
import { NotionClientWrapper } from '@suekou/mcp-notion-server/notion/client.js';

const client = new NotionClientWrapper(
  process.env.NOTION_API_TOKEN,
  {
    timeoutMs: 60000,    // 60 second timeout
    maxRetries: 3,       // Total 4 attempts (1 initial + 3 retries)
    retryDelayMs: 1000   // 1 second between retries
  }
);
```

--------------------------------

### Retrieve Available Tools

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/01-mcp-server.md

Returns the complete list of all available MCP tools.

```typescript
export function getAllTools(): Tool[]
```

```typescript
const tools = getAllTools();
console.log(tools.length); // e.g., 30+
tools.forEach(tool => console.log(tool.name));
```

--------------------------------

### Project Directory Structure

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/README.md

Visual representation of the source code organization for the mcp-notion-server project.

```text
src/
├── index.ts              # CLI entry point
├── mcp/
│   ├── server.ts         # MCP server, tool execution
│   ├── result.ts         # Response formatting
│   └── schema.ts         # Parameter schemas
├── notion/
│   ├── client.ts         # Notion API wrapper
│   ├── types.ts          # Type definitions
│   └── errors.ts         # Error classes
├── tools/                # Tool implementations (30+ tools)
├── prompts/              # Guided workflows
├── resources/            # Reference docs
├── markdown/             # Markdown conversion
└── utils/                # Utilities
```

--------------------------------

### notion_create_data_source_item_workflow

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/09-prompts-resources.md

Create a data source item using schema inspection and simple property values.

```APIDOC
## Prompt: notion_create_data_source_item_workflow

### Description
Create a data source item using schema inspection and simple property values.

### Arguments
- **data_source** (string) - Required - The data source name or ID
- **item** (string) - Required - The item to create, described in natural language

### Example Invocation
{
  "name": "notion_create_data_source_item_workflow",
  "arguments": {
    "data_source": "Tasks",
    "item": "Create a task with title 'Review PR', status 'To Do', and due date next Monday"
  }
}
```

--------------------------------

### Configure MCP Notion Server in JSON

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/00-overview.md

Define the server configuration within an MCP configuration file, including environment variables like the API token.

```json
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "secret_xxx",
        "NOTION_MARKDOWN_CONVERSION": "true"
      }
    }
  }
}
```

--------------------------------

### MCP Server Interface

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/00-overview.md

Methods for managing the MCP server lifecycle and retrieving available tools, prompts, and resources.

```APIDOC
## MCP Server Methods

- `startServer()`: Initialize and start the MCP server.
- `executeRegisteredTool(name)`: Execute a tool by its registered name.
- `getAllTools()`: Retrieve all available tools.
- `getAllPrompts()`: Retrieve all available prompts.
- `getAllResources()`: Retrieve all available resources.
- `getServerInstructions()`: Get system instructions for the server.
- `formatJsonToolResult()`: Format a success response.
- `formatToolError()`: Format an error response.
```

--------------------------------

### listAllUsers

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/02-notion-client.md

Lists all users in the Notion workspace.

```APIDOC
## listAllUsers

### Description
Lists all users in the workspace (requires Enterprise plan).

### Signature
`async listAllUsers(start_cursor?: string, page_size?: number): Promise<ListResponse>`

### Parameters
- **start_cursor** (string) - Optional - Pagination cursor
- **page_size** (number) - Optional - Max results per page

### Return Type
ListResponse
```

--------------------------------

### Configure NOTION_MARKDOWN_CONVERSION

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/13-configuration.md

Enable Markdown conversion for Notion API responses by setting the environment variable to "true".

```json
{
  "env": {
    "NOTION_API_TOKEN": "secret_xxx",
    "NOTION_MARKDOWN_CONVERSION": "true"
  }
}
```

--------------------------------

### Enable specific tools

Source: https://github.com/suekou/mcp-notion-server/blob/main/docs/configuration.md

Use the --enabledTools argument to specify a comma-separated allowlist of tool names to register. If omitted, all tools are registered.

```bash
node build/index.js --enabledTools=notion_retrieve_block,notion_retrieve_block_children,notion_retrieve_page,notion_read_page,notion_query_data_source,notion_retrieve_data_source,notion_find,notion_inspect_data_source,notion_search,notion_list_all_users,notion_retrieve_user,notion_retrieve_bot_user,notion_retrieve_comments
```

--------------------------------

### Standard Tool Error Format

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/12-errors.md

The base structure for all tool execution errors.

```json
{
  "content": [
    {
      "type": "text",
      "text": "{\"error\": {\"message\": \"Error description\"}}"
    }
  ],
  "isError": true
}
```

--------------------------------

### Build MCP App Assets

Source: https://github.com/suekou/mcp-notion-server/blob/main/docs/mcp-apps.md

Command to build the app assets for MCP Apps using pnpm. This command specifically targets the creation of bundled single-file HTML assets.

```bash
pnpm run build:apps
```

--------------------------------

### Retrieve MCP Prompts

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/01-mcp-server.md

Returns the complete list of all available MCP prompts.

```typescript
export function getAllPrompts(): Prompt[]
```

--------------------------------

### Importing MCP App utilities

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/08-app-tools.md

Required imports for integrating Notion MCP apps into the server.

```typescript
import {
  MCP_APP_MIME_TYPE,
  notionAppResources,
  readNotionAppResource,
} from "../apps/index.js";
```

--------------------------------

### notion_create_data_source_item_from_values

Source: https://github.com/suekou/mcp-notion-server/blob/main/docs/tools.md

Creates a data source item from simple values keyed by exact property name.

```APIDOC
## notion_create_data_source_item_from_values

### Description
Creates a data source item from simple values keyed by exact property name.

### Purpose
Add a new item to a data source.

### Parameters
#### Query Parameters
- **data_source_id** (string) - Required - The ID of the data source to create the item in.
- **values** (object) - Required - An object where keys are property names and values are the data for the new item.

### Request Example
```json
{
  "data_source_id": "data_source_id_to_create_in",
  "values": {
    "Name": "New Task",
    "Status": "To Do"
  }
}
```

### Response
#### Success Response (200)
- **item_id** (string) - The ID of the newly created item.

#### Response Example
```json
{
  "item_id": "newly_created_item_id"
}
```
```

--------------------------------

### notion_open_data_source_app

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/08-app-tools.md

Opens an interactive Data Source Explorer for schema inspection, filtering, querying, and item creation.

```APIDOC
## Tool: notion_open_data_source_app

### Description
Opens an interactive Data Source Explorer for schema inspection, filtering, querying, and item creation.

### Parameters
- **data_source_id** (string) - Optional - Optional initial data source ID to load
- **format** (string) - Optional - Response format: 'json' or 'markdown' (default: markdown)

### Request Example
{
  "data_source_id": "12345678-1234-1234-1234-123456789012"
}
```

--------------------------------

### Create Data Source Items

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/00-overview.md

Add new items to data sources using simplified key-value pairs or raw Notion property structures.

```typescript
// Use simple values
POST /tool notion_create_data_source_item_from_values
{
  "data_source_id": "...",
  "values": {
    "Name": "Task Title",
    "Status": "To Do",
    "Due": "2026-12-31",
    "Tags": ["urgent", "project"]
  }
}

// Or raw Notion properties if needed
POST /tool notion_create_data_source_item
{
  "data_source_id": "...",
  "properties": { ... }
}
```

--------------------------------

### notion_open_page_workbench

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/08-app-tools.md

Opens an interactive Page Workbench for reading, editing, and appending to page content.

```APIDOC
## Tool: notion_open_page_workbench

### Description
Opens an interactive Page Workbench for reading, editing, and appending to page content.

### Parameters
- **page_id** (string) - Optional - Optional initial page ID to load
- **format** (string) - Optional - Response format: 'json' or 'markdown' (default: markdown)

### Request Example
{
  "page_id": "12345678-1234-1234-1234-123456789012"
}
```

--------------------------------

### notion_create_data_source_item

Source: https://github.com/suekou/mcp-notion-server/blob/main/docs/tools.md

Create a page item in a data source with raw Notion property JSON.

```APIDOC
## notion_create_data_source_item

### Description
Create a page item in a data source with raw Notion property JSON.

### Method
POST

### Endpoint
/notion/data_source_item/create

### Parameters
#### Request Body
- **data_source_id** (string) - Required - The ID of the data source.
- **properties** (object) - Required - The Notion property JSON for the item.

### Request Example
{
  "data_source_id": "...",
  "properties": { ... }
}

### Response
#### Success Response (200)
- **item_id** (string) - The ID of the created item.

#### Response Example
{
  "item_id": "..."
}
```

--------------------------------

### Define NotionClientOptions configuration

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/10-types.md

Configuration settings for the NotionClientWrapper, including timeout and retry logic.

```typescript
type NotionClientOptions = {
  timeoutMs?: number;
  maxRetries?: number;
  retryDelayMs?: number;
}
```

--------------------------------

### Retrieve MCP Resources

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/01-mcp-server.md

Returns the complete list of all available MCP resources.

```typescript
export function getAllResources(): Resource[]
```

--------------------------------

### notion_list_all_users

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/03-discovery-tools.md

Lists all users in the workspace.

```APIDOC
## notion_list_all_users

### Description
Lists all users in the workspace. Requires Notion Enterprise plan and Organization API key.

### Parameters
- **start_cursor** (string) - Optional - Pagination cursor
- **page_size** (number) - Optional - Max results per page (max 100)
- **response_mode** (string) - Optional - Response detail: 'auto', 'compact', or 'full'
- **format** (string) - Optional - Response format: 'json' or 'markdown'
```

--------------------------------

### Create Notion Data Source Item

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/02-notion-client.md

Creates a new page item within a specified data source using raw Notion property formatting.

```typescript
async createDataSourceItem(
  data_source_id: string,
  properties: NotionJsonObject,
): Promise<PageResponse>
```

--------------------------------

### notion_inspect_data_source

Source: https://github.com/suekou/mcp-notion-server/blob/main/docs/tools.md

Compact data source schema summary.

```APIDOC
## notion_inspect_data_source

### Description
Compact data source schema summary.

### Method
POST

### Endpoint
/notion/data_source/inspect

### Parameters
#### Request Body
- **data_source_id** (string) - Required - The ID of the data source.

### Request Example
{
  "data_source_id": "..."
}

### Response
#### Success Response (200)
- **schema_summary** (object) - A summary of the data source schema.

#### Response Example
{
  "schema_summary": { ... }
}
```

--------------------------------

### Retrieve a Notion database

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/02-notion-client.md

Fetches a database container along with its associated child data sources.

```typescript
async retrieveDatabase(database_id: string): Promise<DatabaseResponse>
```

--------------------------------

### Query Notion Data Sources

Source: https://github.com/suekou/mcp-notion-server/blob/main/_autodocs/00-overview.md

Discover data sources, inspect their schemas, and filter items based on specific property values.

```typescript
// Discover target
GET /tool notion_find { "query": "Task list", "object_type": "data_source" }

// Inspect schema
GET /tool notion_inspect_data_source { "data_source_id": "..." }

// Query items
POST /tool notion_query_data_source_by_values
{
  "data_source_id": "...",
  "filters": [{ "property": "Status", "operator": "equals", "value": "Done" }]
}
```
Tokens:
Raw