Notion MCP Server

Most tools in the Notion MCP server support the following optional parameters to control output:

• format: Specifies the output format. Options are "json" or "markdown". The default is "markdown".
• response_mode: Controls how much data is returned on list-heavy read tools. Options are "auto", "compact", or "full".

Error Handling: Tool errors are returned with isError: true. This allows an AI agent to identify the error and attempt to correct invalid arguments in subsequent calls.

The Notion MCP server provides two optional MCP Apps. These combine a specific tool with a ui:// resource, allowing compatible MCP hosts to render an interactive HTML interface directly within the conversation.

If your host does not support MCP Apps, you must use the provided fallback tools to perform the same actions manually via standard tool calls.

Depending on your setup, use one of the following configurations in your MCP host (e.g., Claude Desktop).

Using npx

This is the easiest way to run the server using the published package.

Using a Local build

Use this if you have cloned the repository and built it locally. You must provide the absolute path to the build/index.js file.

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

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

The project requires Node.js 22 or newer and pnpm.

Use the following commands for local development:

• pnpm install --frozen-lockfile: Install dependencies.
• pnpm run build: Build the project.
• pnpm test: Run tests.
• pnpm run inspector: Launch the MCP inspector for debugging.

To interact with Notion effectively, follow this sequence of tool usage:

1. Discovery: Use notion_find to locate a specific page or data source.
2. Context Gathering: Use notion_read_page to get page content and identify editable block IDs.
3. Schema Inspection: Use notion_inspect_data_source before attempting to query or create items in a database.
4. Data Operations: Use notion_query_data_source_by_values and notion_create_data_source_item_from_values for structured database work.
5. Editing: Use simplified tools like notion_append_markdown, notion_append_content, notion_update_content, or notion_update_content_batch for standard page edits.
6. Advanced Operations: Fall back to raw Notion API tools only when the simplified tools cannot handle the specific JSON shape required.

To use the Notion MCP server with an MCP host like Claude Desktop, add the following configuration to your host's settings. This uses npx to run the server directly without a manual build step.

Note: You must replace your-integration-token with the secret token obtained from your Notion integration dashboard.

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

If you are developing or modifying the MCP Apps, use the following commands to build the assets. The build process uses Vite to bundle single-file HTML assets into build/apps/assets.

To build only the app assets:

pnpm run build:apps

To perform a full project build:

pnpm run build

The server provides specialized MCP App resources designed for interactive UI workflows. These resources use a unique MIME type text/html;profile=mcp-app to signal to the MCP host that they are interactive applications rather than plain text.

Available interactive apps include:

• ui://notion/data-source-explorer: An interactive workbench for schema exploration, querying, and item creation.
• ui://notion/page-workbench: An interactive workbench for reading pages and performing simple block editing.

When a host requests these URIs via readNotionAppResource, the server returns the HTML content along with specific Content Security Policy (CSP) metadata in the _meta.ui.csp field to ensure secure execution within the host environment.

// Example URIs for interactive apps:
// ui://notion/data-source-explorer
// ui://notion/page-workbench

The server requires specific environment variables to function correctly.

• NOTION_API_TOKEN (Required): Your Notion internal integration token. The server uses this for authentication and sets the Notion-Version header to 2026-03-11.
• NOTION_MARKDOWN_CONVERSION (Optional): Set to "true" to enable experimental Markdown conversion for Notion API objects. Note that most tools default to "markdown" if they are convertible, but this variable must be set for the conversion logic to activate.

{
  "env": {
    "NOTION_API_TOKEN": "your-integration-token",
    "NOTION_MARKDOWN_CONVERSION": "true"
  }
}