Notion MCP Server for Claude Desktop: Setup & Config

What you can do with Notion in Claude Desktop

Pick it for compact Notion context and schema-aware editing without relying on raw API JSON for routine work.

• Locate pages and read compact content with stable block IDs
• Query Notion data sources using schema-aware filters
• Append Markdown or batch-edit common page blocks

Before you start: Notion in Claude Desktop

• npx
• An MCP host
• A Notion internal integration token
• Content shared with the integration and appropriate capabilities

Restart the MCP host after configuration. Grant only needed capabilities and share target pages or databases with the integration. Development prerequisites specify Node.js 22 or newer and pnpm.

Notion Claude Desktop configuration

1. Choose Claude Desktop configuration scope

   For Notion MCP Server, open macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json. Merge under mcpServers via Settings → Developer → Edit Config when available.

2. Add Notion MCP Server to Claude Desktop

   Use the mcp-notion-server entry below in mcpServers. Keep Notion MCP Server's documented stdio connection fields and your other Claude Desktop entries.

3. Check Notion MCP Server in Claude Desktop

   Notion MCP Server: Fully quit and reopen Claude Desktop; check developer diagnostics.

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

Notion tools available to Claude Desktop

Notion's stored tool list documents 31 tools; compare it with Claude Desktop's connected tool list, because the stored list is not a live check.

notion_open_data_source_app

When Claude Desktop requests notion_open_data_source_app from Notion, review the action before approving it.

Open an interactive app for schema inspection, filtering, queries, and item creation.

notion_open_page_workbench

When Claude Desktop requests notion_open_page_workbench from Notion, review the action before approving it.

Open an interactive app for page reading, block selection, simple edits, and Markdown append.

notion_append_block_children

When Claude Desktop requests notion_append_block_children from Notion, review the action before approving it.

Insert child blocks beneath a parent at a specified position.

notion_append_content

When Claude Desktop requests notion_append_content from Notion, review the action before approving it.

Append common content types without constructing raw block JSON.

notion_append_markdown

When Claude Desktop requests notion_append_markdown from Notion, review the action before approving it.

Append supported Markdown elements as Notion blocks.

notion_update_content

When Claude Desktop requests notion_update_content from Notion, review the action before approving it.

Replace simple content fields on an existing block of the matching type.

notion_update_content_batch

When Claude Desktop requests notion_update_content_batch from Notion, review the action before approving it.

Validate target block types and apply several simple content updates.

notion_retrieve_block

When Claude Desktop requests notion_retrieve_block from Notion, review the action before approving it.

Fetch a single Notion block.

notion_retrieve_block_children

When Claude Desktop requests notion_retrieve_block_children from Notion, review the action before approving it.

Fetch blocks nested beneath a parent.

notion_delete_block

When Claude Desktop requests notion_delete_block from Notion, review the action before approving it.

Remove a selected Notion block.

notion_update_block

When Claude Desktop requests notion_update_block from Notion, review the action before approving it.

Replace selected block fields using the raw API shape.

notion_retrieve_page

When Claude Desktop requests notion_retrieve_page from Notion, review the action before approving it.

Fetch page metadata from Notion.

notion_read_page

When Claude Desktop requests notion_read_page from Notion, review the action before approving it.

Read bounded page content as an outline or Markdown with block identifiers.

notion_update_page_properties

When Claude Desktop requests notion_update_page_properties from Notion, review the action before approving it.

Change properties on a page or database item.

notion_list_all_users

When Claude Desktop requests notion_list_all_users from Notion, review the action before approving it.

List workspace users; the tool data notes Enterprise and Organization API key requirements.

notion_retrieve_user

When Claude Desktop requests notion_retrieve_user from Notion, review the action before approving it.

Fetch a user by ID; the tool data notes Enterprise and Organization API key requirements.

notion_retrieve_bot_user

When Claude Desktop requests notion_retrieve_bot_user from Notion, review the action before approving it.

notion_retrieve_database

When Claude Desktop requests notion_retrieve_database from Notion, review the action before approving it.

notion_create_database

When Claude Desktop requests notion_create_database from Notion, review the action before approving it.

notion_create_data_source

When Claude Desktop requests notion_create_data_source from Notion, review the action before approving it.

notion_query_data_source

When Claude Desktop requests notion_query_data_source from Notion, review the action before approving it.

notion_query_data_source_by_values

When Claude Desktop requests notion_query_data_source_by_values from Notion, review the action before approving it.

notion_retrieve_data_source

When Claude Desktop requests notion_retrieve_data_source from Notion, review the action before approving it.

notion_update_data_source

When Claude Desktop requests notion_update_data_source from Notion, review the action before approving it.

notion_create_data_source_item

When Claude Desktop requests notion_create_data_source_item from Notion, review the action before approving it.

notion_create_data_source_item_from_values

When Claude Desktop requests notion_create_data_source_item_from_values from Notion, review the action before approving it.

notion_create_comment

When Claude Desktop requests notion_create_comment from Notion, review the action before approving it.

notion_retrieve_comments

When Claude Desktop requests notion_retrieve_comments from Notion, review the action before approving it.

notion_find

When Claude Desktop requests notion_find from Notion, review the action before approving it.

notion_inspect_data_source

When Claude Desktop requests notion_inspect_data_source from Notion, review the action before approving it.

notion_search

When Claude Desktop requests notion_search from Notion, review the action before approving it.

Notion: full stored tool descriptions

Troubleshooting Notion in Claude Desktop

• Fully quit and reopen Claude Desktop for Notion MCP Server. If npx @suekou/mcp-notion-server (Node.js/npm) is missing, check the desktop process's PATH, which may differ from your terminal.
• In Claude Desktop's Notion MCP Server entry, check NOTION_API_TOKEN. Keep secrets out of shared screenshots and repositories.
• Notion MCP Server uses stdio here: Claude Desktop must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Only shared content and granted capabilities are accessible
• Known limitation: Some user lookup tools require Enterprise and an Organization API key
• Known limitation: Markdown append supports a limited safe subset
• General Claude Desktop troubleshooting lives in the /clients/claude-desktop guide.

Frequently asked questions