### 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
```

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

### 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 MCP Server System Instructions

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

Retrieves the system instructions for AI models interacting with the MCP server. These instructions guide the AI on how to prioritize and use Notion tools effectively.

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

```plaintext
Use high-level Notion tools first: notion_find, notion_read_page, notion_inspect_data_source, schema-aware query/create tools, and simple content tools.
Use raw Notion JSON tools only when simplified tools do not support the requested block, property, or API shape.
Use notion_create_database for new databases; notion_create_data_source only adds another data source to an existing database.
Prefer data_source_id for schema, query, and item creation workflows. Use notion_retrieve_database only to discover child data sources from a database container.
```

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

### getServerInstructions

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

Retrieves the system instructions for AI models, guiding them on how to effectively use Notion tools and resources.

```APIDOC
## getServerInstructions

### Description
Retrieves the system instructions that guide AI models on how to interact with Notion tools and resources. These instructions provide a strategy for tool selection and usage, prioritizing high-level and simplified tools.

### Function Signature
```typescript
function getServerInstructions(): string
```

### Parameters
None

### Returns
- **string** - A string containing the server's system instructions for AI models.

### Content Example
```
Use high-level Notion tools first: notion_find, notion_read_page, notion_inspect_data_source, schema-aware query/create tools, and simple content tools.
Use raw Notion JSON tools only when simplified tools do not support the requested block, property, or API shape.
Use notion_create_database for new databases; notion_create_data_source only adds another data source to an existing database.
Prefer data_source_id for schema, query, and item creation workflows. Use notion_retrieve_database only to discover child data sources from a database container.
```
```

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

### startServer

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

Starts the MCP server with Notion integration, registering tools, prompts, and resources, and establishing a connection for tool execution.

```APIDOC
## startServer

### Description
Starts the MCP server with Notion integration. This function initializes the Notion client, registers all available tools (optionally filtered), prompts, and resources, and then connects to the MCP transport (stdio) to handle tool execution and resource reading.

### Function Signature
```typescript
async function startServer(notionToken: string, enabledToolsSet?: Set<string>, enableMarkdownConversion?: boolean): Promise<void>
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

#### Function Parameters
- **notionToken** (string) - Required - Notion API integration token.
- **enabledToolsSet** (Set<string>) - Optional - A set of tool names to enable. If empty, all tools are enabled.
- **enableMarkdownConversion** (boolean) - Optional - Whether to convert Notion responses to Markdown format.

### Throws
Error if the Notion token is invalid or if the connection fails.

### Example
```typescript
import { startServer } from "./mcp/server.js";

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

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

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

### Install Project Dependencies

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

Installs all necessary dependencies for the project using pnpm. This command should be run before building or testing.

```bash
pnpm install
```

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

### Start MCP Server with Notion Integration

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

Initiates the MCP server, enabling Notion integration. Configure which tools are active and whether to convert responses to Markdown.

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

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

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

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

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

### Fetch and Use Prompts and Resources

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

Demonstrates how to import and use functions to get all prompts and resources, find a specific prompt by name, execute a prompt with parameters, and read resource content. Requires importing functions from './mcp/server.js', './prompts/index.js', and './resources/index.js'.

```typescript
import { getAllPrompts, getAllResources } from "./mcp/server.js";

const prompts = getAllPrompts();
const resources = getAllResources();

// Find a prompt
const findTargetPrompt = prompts.find(p => p.name === "notion_find_target");

// Get prompt result
const { getNotionPrompt } = await import("./prompts/index.js");
const result = getNotionPrompt("notion_find_target", { target: "Project Q" });
console.log(result.messages[0].content.text);

// Get resource
const { readNotionResource } = await import("./resources/index.js");
const guide = readNotionResource("notion://server/guide");
console.log(guide.contents[0].text);
```

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

### Run Generic MCP Host

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

Starts the Notion MCP server for a generic MCP-compatible host. The server communicates via stdio and requires environment variables to be set in the host's process environment.

```bash
node build/index.js
```

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

### Handle Unknown Tool Error

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

Example of an error message when a specified tool name is unknown or disabled.

```text
Error: Unknown tool: notion_invalid_name
```

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

### Get All Available MCP Resources

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

Retrieves an array of all available resources for the MCP system. This includes Notion-specific guides and tools, as well as UI applications for data source exploration and page management.

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

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

### Launch MCP Inspector

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

Starts the MCP Inspector, an interactive debugger that opens at `http://localhost:3000`. Use this tool to test tools, prompts, and resources locally.

```bash
pnpm run inspector
```

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

### Sort Object Example

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

Example of a sort object for notion_query_data_source_by_values. Specifies property and direction.

```typescript
{
  property: string,     // Exact property name
  direction?: string    // "ascending" or "descending"
}
```

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

### Get All Available MCP Prompts

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

Retrieves an array of all available prompts for the MCP system. These prompts are designed to guide specific workflows like finding targets or creating data source items.

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

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

### Build Notion MCP Server

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

Installs dependencies and builds the TypeScript project into an ES module located at build/index.js.

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

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

### 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"
      }
    }
  }
}
```

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

### Filter Object Example

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

Example of a filter object for notion_query_data_source_by_values. Specifies property, operator, and value.

```typescript
{
  property: string,     // Exact property name from notion_inspect_data_source
  operator?: string,    // equals, does_not_equal, contains, does_not_contain,
                        // greater_than, less_than, greater_than_or_equal_to,
                        // less_than_or_equal_to, before, after, on_or_before,
                        // on_or_after, is_empty, is_not_empty
  value?: any          // Type-aware: string/number/boolean/date depending on property
}
```

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

### 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
```

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

### Get All Available MCP Tools

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

Retrieves an array of all available tools within the MCP system. This includes tools for app, block, content, page, discovery, and data source management.

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

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

### 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
}
```

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

### Query Notion Data Source Items

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

Retrieves items from a data source based on provided filters and sorting criteria. Supports pagination with start cursor and page size. Note that the page size is capped at 100.

```typescript
const results = await client.queryDataSource(
  "ds_id",
  { "property": "Status", "select": { "equals": "Done" } },
  [{ "property": "Created", "direction": "descending" }],
  undefined,
  20
);
```

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

### Build Project

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

Builds the project, outputting an ES module to `build/index.js`. This command is used to prepare the project for deployment or distribution.

```bash
pnpm run build
```

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

### Create a New Database

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

Creates a new database with initial schema and optional properties like title, description, and icon. The parent can be a page or workspace.

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

const db = await client.createDatabase({
  parent: { type: "page_id", page_id: "page_id" },
  initial_data_source: {
    properties: {
      "Name": { "title": {} },
      "Done": { "checkbox": {} }
    }
  }
});
```

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

### Tool Registration Loop

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

Demonstrates the process of iterating through available tools and registering them with the MCP server, including their metadata and execution logic.

```typescript
for (const tool of filterTools(getAllTools(), enabledToolsSet)) {
  server.registerTool(
    tool.name,
    {
      title: tool.annotations?.title,
      description: tool.description,
      inputSchema: toolInputSchema(tool),
      annotations: tool.annotations,
      _meta: tool._meta
    },
    async (toolArguments) =>
      executeRegisteredTool(
        tool.name,
        toolArguments,
        notionClient,
        enableMarkdownConversion
      )
  );
}
```

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

### Retrieve Comments

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

Fetches comments associated with a block or page. Supports pagination with optional start cursor and page size.

```typescript
async retrieveComments(
  block_id: string,
  start_cursor?: string,
  page_size?: number
): Promise<ListResponse>
```

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

### Create a New Notion Database

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

Create a new Notion database with an initial data source, including property schema. Specify the parent page or workspace, and optionally provide a title, description, and display format. The `initial_data_source` must contain a `properties` object defining the database schema.

```json
{
  "parent": { "type": "page_id", "page_id": "parent_page_id" },
  "initial_data_source": {
    "properties": {
      "Name": { "title": {} },
      "Status": { "select": { "options": [{ "name": "Todo" }, { "name": "Done" }] } },
      "Done": { "checkbox": {} }
    }
  },
  "title": [{ "type": "text", "text": { "content": "My Database" } }]
}
```

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

### retrieveComments

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

Retrieves comments associated with a specific block or page. Supports pagination with optional start cursor and page size parameters.

```APIDOC
## GET /retrieveComments

### Description
Retrieve comments on a block or page.

### Method
GET

### Endpoint
/retrieveComments

### Parameters
#### Path Parameters
- **block_id** (string) - Required - Block or page UUID
#### Query Parameters
- **start_cursor** (string) - Optional - Pagination cursor
- **page_size** (number) - Optional - Results per page

### Response
#### Success Response (200)
- **ListResponse** - ListResponse with CommentResponse items
```

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

### Constructor

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

Initializes a new instance of the NotionClientWrapper. It takes a Notion API integration token and optional configuration options.

```APIDOC
## Constructor NotionClientWrapper

### Description
Initializes a new instance of the NotionClientWrapper. It takes a Notion API integration token and optional configuration options.

### Signature
```typescript
constructor(
  token: string,
  options?: NotionClientOptions
): NotionClientWrapper
```

### Parameters
#### Parameters
- **token** (string) - Required - Notion API integration token (from integration settings)
- **options** (NotionClientOptions) - Optional - Optional client configuration

### NotionClientOptions

| Field | Type | Default | Description |
|---|---|---|---|
| timeoutMs | number | 30000 | Request timeout in milliseconds |
| maxRetries | number | 2 | Maximum number of retry attempts for retryable errors (429, 5xx) |
| retryDelayMs | number | 500 | Base delay between retries in milliseconds |

### Example
```typescript
import { NotionClientWrapper } from "./notion/client.js";

const client = new NotionClientWrapper(process.env.NOTION_API_TOKEN, {
  timeoutMs: 60_000,
  maxRetries: 3,
});
```
```

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

### Retrieve Bot User Information

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

Use `notion_retrieve_bot_user` to get information about the bot user associated with the current token. The response format can be specified.

```json
{
  "format": "json"
}
```

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

### Run Notion MCP Server

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

Execute the Notion MCP Server using npm. Ensure the NOTION_API_TOKEN environment variable is set.

```bash
npm exec @suekou/mcp-notion-server
```

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

### DatePropertyValue Type

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

Represents a date property value, which can include a start and end date in ISO 8601 format. The end date can be null for single-day events.

```typescript
type DatePropertyValue = {
  start?: string;
  end?: string | null;
  [key: string]: unknown;
}
```

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

### MCP Client Prompts and Resources

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

Lists available prompts and resource URIs for use with MCP-compatible clients.

```text
notion_find_target
notion_create_data_source_item_workflow
notion_query_data_source_items_workflow
notion_append_page_content
```

```text
notion://server/guide
notion://server/tools
ui://notion/data-source-explorer
ui://notion/page-workbench
```

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

### 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
```

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

### Troubleshoot Permission Denied Errors

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

Addresses 'Permission Denied' errors by verifying integration access rights. Ensure the integration has content access, required capabilities, and that the page/database is shared.

```text
Notion API request failed (403 forbidden): Access denied
```

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

### 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"
}
```
```

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

### Retrieve a Specific Notion User

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

Use `notion_retrieve_user` to get a user's information by their UUID. Note: This requires an Enterprise plan with an Organization API key.

```json
{
  "user_id": "user_uuid_123",
  "format": "json"
}
```

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

### NotionResponse Union Type

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

A union type representing all possible response types from the Notion API. This is used to determine how to render different content types, for example, by the `NotionClientWrapper.toMarkdown()` method.

```typescript
type NotionResponse = 
  | PageResponse
  | DatabaseResponse
  | DataSourceResponse
  | BlockResponse
  | ListResponse
  | UserResponse
  | CommentResponse
```

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

### 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"
      }
    }
  }
}
```

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

### Configure Notion MCP Server for Local Development

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

Configures the Notion MCP server for local development using a locally built checkout. Specifies the node command, the path to the build index, and environment variables.

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

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

### Append Children to Notion Block Example

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

This JSON object demonstrates how to append new blocks as children to an existing Notion block. It supports complex rich text and nested structures.

```json
{
  "block_id": "page_id",
  "children": [
    {
      "type": "paragraph",
      "paragraph": {
        "rich_text": [
          { "type": "text", "text": { "content": "Hello" } }
        ]
      }
    }
  ]
}
```

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

### Update Notion Page Properties Example

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

Use this JSON object to update specific properties of a Notion page. Ensure the 'page_id' is correct and 'properties' are formatted as raw Notion JSON.

```json
{
  "page_id": "abc123...",
  "properties": {
    "Status": { "select": { "name": "In Progress" } },
    "Assignee": { "people": [{ "id": "user_uuid" }] }
  }
}
```

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

### 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": "..."
}
```

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

### Configure Notion MCP Server for Claude Desktop

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

Adds Notion MCP server configuration to the Claude Desktop settings. This includes the command to run, arguments, and environment variables.

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

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

### Create Notion Data Source Item Prompt

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

Use this prompt to create a new item in a Notion data source. It requires the data source name/ID and a natural language description of the item to create.

```json
{
  "name": "notion_create_data_source_item_workflow",
  "arguments": {
    "data_source": "Tasks",
    "item": "Add a task for 'Review PR' with status Done and due date June 15"
  }
}
```

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

### Inspect Notion Data Source Schema

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

Use `notion_inspect_data_source` to get a summary of a data source's properties and types. This is useful before creating or updating items, choosing property values, or building query filters.

```json
{
  "data_source_id": "abc123..."
}
```

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

### getAllPrompts

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

Retrieves an array of all available MCP prompts, which are pre-defined workflows for common Notion operations.

```APIDOC
## getAllPrompts

### Description
Retrieves an array of all available prompts within the MCP server. These prompts represent pre-defined workflows or sequences of actions designed to simplify common Notion tasks.

### Function Signature
```typescript
function getAllPrompts(): Prompt[]
```

### Parameters
None

### Returns
- **Prompt[]** - An array of Prompt objects, detailing the available prompts.

### Prompts:

1. **notion_find_target** — Find the right Notion page or data source before reading or editing.
2. **notion_create_data_source_item_workflow** — Create a data source item using schema inspection.
3. **notion_query_data_source_items_workflow** — Query data source items using simple filters.
4. **notion_append_page_content** — Append or update page content using simplified tools.
```

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

### 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"
      }
    }
  }
}
```

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

### 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"
      }
    }
  }
}
```

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

### Find Notion Target Prompt

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

Use this prompt to find the correct Notion page or data source before performing read, edit, or create operations. It accepts a target string for searching.

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

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

### MCP Server Capabilities Configuration

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

Shows the configuration object for advertising server capabilities to MCP clients, including tools, prompts, resources, and extensions like the Notion app.

```typescript
capabilities: {
  tools: {},
  prompts: {},
  resources: {},
  extensions: {
    "io.modelcontextprotocol/ui": {
      mimeTypes: ["application/vnd.suekou.mcp-notion-app"]
    }
  }
}
```

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

### getAllResources

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

Retrieves an array of all available MCP resources, including documentation links and UI application entry points.

```APIDOC
## getAllResources

### Description
Retrieves an array of all available resources within the MCP server. These resources include documentation links and entry points for UI applications.

### Function Signature
```typescript
function getAllResources(): Resource[]
```

### Parameters
None

### Returns
- **Resource[]** - An array of Resource objects, detailing the available resources.

### Resources:

**Notion Resources (2):**
- `notion://server/guide` — Notion MCP Workflow Guide
- `notion://server/tools` — Notion MCP Tool Map

**UI App Resources:**
- `ui://notion/data-source-explorer` — Data Source Explorer app
- `ui://notion/page-workbench` — Page Workbench app
```

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

### Format Code

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

Formats the code according to predefined style rules using Biome. This ensures a consistent code style across the project.

```bash
pnpm format
```

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

### Run Notion MCP Server Tests

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

Executes the test suite for the Notion MCP server. Use 'pnpm test' to run all tests once or 'pnpm test:watch' for continuous testing.

```bash
pnpm test

pnpm test:watch
```

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

### Create Data Source Item

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

Create a new item in a data source using raw Notion JSON for properties.

```javascript
await notion_create_data_source_item({
  data_source_id: "...",
  properties: {
    // ... item properties in raw Notion format
  },
  format: "json"
});
```

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

### Linting and Formatting Commands

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

Provides commands for code quality checks and formatting. Use 'lint' and 'format' to maintain code standards, and 'check' to run all verification steps.

```bash
pnpm lint

```

```bash
pnpm lint:fix

```

```bash
pnpm format

```

```bash
pnpm check

```

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

### Initialize NotionClientWrapper

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

Instantiate the NotionClientWrapper with your Notion API token and optional configuration for timeouts and retries.

```typescript
import { NotionClientWrapper } from "./notion/client.js";

const client = new NotionClientWrapper(process.env.NOTION_API_TOKEN, {
  timeoutMs: 60_000,
  maxRetries: 3,
});
```

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

### Run Tests Once

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

Executes all tests in the project once using the Vitest framework. This is useful for verifying code correctness after changes.

```bash
pnpm test
```

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

### notion_open_data_source_app

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

Opens the interactive Data Source Explorer.

```APIDOC
## notion_open_data_source_app

### Description
Opens the interactive Data Source Explorer.

### Optional Input
- **data_source_id** (string) - The initial data source ID to open in the explorer.

### Request Example
```json
{
  "data_source_id": "initial_data_source_id"
}
```

### Response
This tool does not return a direct response but opens an application interface.
```

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

### createDatabase

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

Creates a new database with an initial data source schema. It requires parent information and can optionally include a title, description, inline display setting, icon, and cover.

```APIDOC
## POST /createDatabase

### Description
Create a new database with initial data source.

### Method
POST

### Endpoint
/createDatabase

### Parameters
#### Request Body
- **args.parent** (object) - Required - Parent page or workspace: `{ type: "page_id", page_id: "..." }`
- **args.initial_data_source** (object) - Required - Initial schema under `properties`
- **args.title** (RichTextItemResponse[]) - Optional - Database title
- **args.description** (RichTextItemResponse[]) - Optional - Database description
- **args.is_inline** (boolean) - Optional - Display inline in parent
- **args.icon** (object) - Optional - Notion icon object
- **args.cover** (object) - Optional - Notion cover image object

### Response
#### Success Response (200)
- **DatabaseResponse** - DatabaseResponse
```

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

### Create Data Source

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

Add an additional data source to an existing database. Do not use this for creating new databases.

```javascript
await notion_create_data_source({
  parent: {
    type: "database_id",
    database_id: "..."
  },
  title: [
    {
      type: "text",
      text: {
        content: "New Data Source Title"
      }
    }
  ],
  properties: {
    // ... property schema
  },
  format: "json"
});
```

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

### notion_open_page_workbench

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

Opens the interactive Page Workbench.

```APIDOC
## notion_open_page_workbench

### Description
Opens the interactive Page Workbench.

### Optional Input
- **page_id** (string) - The initial page ID to open in the workbench.

### Request Example
```json
{
  "page_id": "initial_page_id"
}
```

### Response
This tool does not return a direct response but opens an application interface.
```

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

### Query Notion Data Source Items Prompt

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

Use this prompt to query items from a Notion data source based on natural language descriptions. It requires the data source name/ID and the query string.

```json
{
  "name": "notion_query_data_source_items_workflow",
  "arguments": {
    "data_source": "Tasks",
    "query": "Find all incomplete tasks due before June 1"
  }
}
```

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

### 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
```

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

### notion_open_page_workbench

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

Opens the interactive Page Workbench MCP App for reading page content, selecting blocks, updating blocks, and appending markdown.

```APIDOC
## notion_open_page_workbench

### Description
Open interactive Page Workbench MCP App.

### Method
Interactive UI

### Parameters
#### Input Parameters
- **page_id** (string) - No - Optional initial page to read
- **format** (string) - No - Response format: "json" or "markdown"

### Capabilities
- Page content reading
- Block ID selection
- Simple block updating
- Markdown appending
```

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

### Filter Enabled Tools via Command-Line

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

Filters the available tools for the MCP client using the --enabledTools command-line argument. Provide a comma-separated string of tool names.

```bash
node build/index.js --enabledTools=notion_find,notion_read_page,notion_append_content
```

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

### 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
```

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

### Configure Notion MCP Server for Cursor

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

Adds Notion MCP server configuration to Cursor's settings. This specifies the command, arguments, and environment variables for the Notion server.

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

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

### notion_open_data_source_app

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

Opens the interactive Data Source Explorer MCP App, allowing for schema inspection, filter building, querying, and item creation.

```APIDOC
## notion_open_data_source_app

### Description
Open interactive Data Source Explorer MCP App.

### Method
Interactive UI

### Parameters
#### Input Parameters
- **data_source_id** (string) - No - Optional initial data source to inspect
- **format** (string) - No - Response format: "json" or "markdown"

### Capabilities
- Schema inspection
- Filter building UI
- Querying with simple filters
- Item creation from simple values
```

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

### Handle 404 Not Found Errors

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

Details how to manage 404 Not Found errors, which occur when a requested resource does not exist, and suggests using a search function to locate it.

```typescript
if (error instanceof NotionApiError && error.status === 404) {
  console.error(`Resource not found: ${toolArguments.page_id}`);
  // Guide user to use notion_find to locate the resource
}
```

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

### Create a Notion Data Source

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

Creates a new data source within a specified database. You must provide the parent database reference and the property schema for the data source. An optional title can also be included.

```typescript
const ds = await client.createDataSource(
  { type: "database_id", database_id: "db_id" },
  {
    "Name": { "title": {} },
    "Status": { "select": { "options": [...] } }
  }
);
```

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

### Open Data Source Explorer MCP App

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

Launches the interactive Data Source Explorer MCP App. This tool allows for schema inspection, filter building, querying, and item creation. You can optionally specify an initial data source ID to inspect.

```json
{
  "data_source_id": "ds_id",
  "format": "json"
}
```

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

### 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"
}
```
```

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

### Query Data Source (Simple)

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

Query a data source using simple, schema-aware filters and sorts. Use this instead of notion_query_data_source for simple property types.

```javascript
await notion_query_data_source_by_values({
  data_source_id: "...",
  filters: [
    {
      property: "Status",
      operator: "equals",
      value: "Done"
    }
  ],
  match: "all",
  sorts: [
    {
      property: "Created Time",
      direction: "descending"
    }
  ],
  format: "json"
});
```

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

### Enable Markdown Conversion

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

Set the NOTION_MARKDOWN_CONVERSION environment variable to "true" in your MCP host configuration to enable markdown conversion in responses.

```json
{
  "env": {
    "NOTION_MARKDOWN_CONVERSION": "true"
  }
}
```

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

### Enable Notion Markdown Conversion

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

Enables experimental Markdown conversion for Notion responses by setting the NOTION_MARKDOWN_CONVERSION environment variable to "true". When disabled, responses remain in JSON format.

```bash
export NOTION_MARKDOWN_CONVERSION="true"
```

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

### Initialize NotionClientWrapper with Custom Options

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

Initializes the NotionClientWrapper with custom options for timeout, retries, and retry delay. This is useful for fine-tuning the client's behavior in custom integrations.

```typescript
import { NotionClientWrapper } from "./notion/client.js";

const client = new NotionClientWrapper(token, {
  timeoutMs: 60_000,      // 60 second timeout
  maxRetries: 3,          // Retry up to 3 times
  retryDelayMs: 1_000     // 1 second initial delay
});
```

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

### 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": "..."
}
```

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

### Handle Malformed Tool Arguments

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

Demonstrates how non-object tool arguments are treated as empty objects, potentially leading to missing parameter errors.

```typescript
// If toolArgumentsInput is not an object:
const toolArguments = isRecord(toolArgumentsInput) ? toolArgumentsInput : {};
```

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

### getAllTools

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

Retrieves an array of all available MCP tools, categorized by their function (App, Block, Content, Page, Discovery, Data Source).

```APIDOC
## getAllTools

### Description
Retrieves an array containing all available tools within the MCP server. These tools are categorized to help users understand their purpose and scope.

### Function Signature
```typescript
function getAllTools(): Tool[]
```

### Parameters
None

### Returns
- **Tool[]** - An array of Tool objects, representing all available MCP tools.

### Tool Categories and Examples:

**App Tools (2):**
- `notion_open_data_source_app`
- `notion_open_page_workbench`

**Block Tools (5):**
- `notion_append_block_children`
- `notion_retrieve_block`
- `notion_retrieve_block_children`
- `notion_update_block`
- `notion_delete_block`

**Content Tools (4):**
- `notion_append_content`
- `notion_append_markdown`
- `notion_update_content`
- `notion_update_content_batch`

**Page Tools (3):**
- `notion_retrieve_page`
- `notion_read_page`
- `notion_update_page_properties`

**Discovery Tools (8):**
- `notion_list_all_users`
- `notion_retrieve_user`
- `notion_retrieve_bot_user`
- `notion_create_comment`
- `notion_retrieve_comments`
- `notion_find`
- `notion_inspect_data_source`
- `notion_search`

**Data Source Tools (9):**
- `notion_create_database`
- `notion_create_data_source`
- `notion_retrieve_database`
- `notion_retrieve_data_source`
- `notion_update_data_source`
- `notion_query_data_source`
- `notion_query_data_source_by_values`
- `notion_create_data_source_item`
- `notion_create_data_source_item_from_values`
```

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

### Create Notion Data Source Item with Values

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

Use this function to create a new Notion item with simple property values. It's suitable when property validation is needed and you want values automatically converted to Notion format. Ensure you have the necessary integration capabilities.

```json
{
  "data_source_id": "ds_id",
  "values": {
    "Name": "New Task",
    "Status": "In Progress",
    "Tags": ["urgent", "review"],
    "Due": "2026-06-15",
    "Done": false
  }
}
```

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

### Success Response Format

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

Shows the JSON structure for successful tool execution responses, including content and structured content.

```json
{
  "content": [
    {
      "type": "text",
      "text": "JSON or Markdown content"
    }
  ],
  "structuredContent": {...}
}
```

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

### notion_create_data_source_item_from_values

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

Create a page item in a data source from simple property values.

```APIDOC
## notion_create_data_source_item_from_values

### Description
Create a page item in a data source from simple property values.

### Method
POST

### Endpoint
/notion/data_source_item/create_from_values

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

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

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

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

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

### List All Notion Workspace Users

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

Use `notion_list_all_users` to retrieve a list of all users in the workspace. Pagination and response mode can be controlled. Note: Requires an Enterprise plan with an Organization API key.

```json
{
  "start_cursor": "cursor_string",
  "page_size": 50,
  "response_mode": "compact",
  "format": "json"
}
```

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

### Notion MCP Tool Map URIs and MIME Types

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

Provides URIs and MIME types for accessing the Notion MCP Tool Map and UI applications.

```text
URI: notion://server/tools
MIME Type: text/markdown
```

```text
URI: ui://notion/data-source-explorer
MIME Type: application/vnd.suekou.mcp-notion-app
```

```text
URI: ui://notion/page-workbench
MIME Type: application/vnd.suekou.mcp-notion-app
```