Notion MCP Server for Claude Code: Setup & Config

What you can do with Notion in Claude Code

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

• Append Markdown or batch-edit common page blocks
• Create data source items from simple property values
• Use interactive Notion exploration and editing apps

Before you start: Notion in Claude Code

• 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 Code configuration

1. Choose Claude Code configuration scope

   For Notion MCP Server, open Project scope: .mcp.json at the repository root. Project JSON: merge into mcpServers; user scope: use the CLI.

2. Add Notion MCP Server to Claude Code

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

3. Check Notion MCP Server in Claude Code

   Notion MCP Server: Inspect claude mcp list and /mcp status.

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

claude mcp add-json --scope project 'mcp-notion-server' '{"type":"stdio","command":"npx","args":["-y","@suekou/mcp-notion-server"],"env":{"NOTION_API_TOKEN":"<Notion internal integration token>"}}'

Notion tools available to Claude Code

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

notion_open_data_source_app

For Notion's notion_open_data_source_app, review the permission request and arguments in Claude Code before approval.

notion_open_page_workbench

For Notion's notion_open_page_workbench, review the permission request and arguments in Claude Code before approval.

notion_append_block_children

For Notion's notion_append_block_children, review the permission request and arguments in Claude Code before approval.

Insert child blocks beneath a parent at a specified position.

notion_append_content

For Notion's notion_append_content, review the permission request and arguments in Claude Code before approval.

Append common content types without constructing raw block JSON.

notion_append_markdown

For Notion's notion_append_markdown, review the permission request and arguments in Claude Code before approval.

Append supported Markdown elements as Notion blocks.

notion_update_content

For Notion's notion_update_content, review the permission request and arguments in Claude Code before approval.

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

notion_update_content_batch

For Notion's notion_update_content_batch, review the permission request and arguments in Claude Code before approval.

Validate target block types and apply several simple content updates.

notion_retrieve_block

For Notion's notion_retrieve_block, review the permission request and arguments in Claude Code before approval.

Fetch a single Notion block.

notion_retrieve_block_children

For Notion's notion_retrieve_block_children, review the permission request and arguments in Claude Code before approval.

Fetch blocks nested beneath a parent.

notion_delete_block

For Notion's notion_delete_block, review the permission request and arguments in Claude Code before approval.

Remove a selected Notion block.

notion_update_block

For Notion's notion_update_block, review the permission request and arguments in Claude Code before approval.

notion_retrieve_page

For Notion's notion_retrieve_page, review the permission request and arguments in Claude Code before approval.

notion_read_page

For Notion's notion_read_page, review the permission request and arguments in Claude Code before approval.

notion_update_page_properties

For Notion's notion_update_page_properties, review the permission request and arguments in Claude Code before approval.

notion_list_all_users

For Notion's notion_list_all_users, review the permission request and arguments in Claude Code before approval.

notion_retrieve_user

For Notion's notion_retrieve_user, review the permission request and arguments in Claude Code before approval.

notion_retrieve_bot_user

For Notion's notion_retrieve_bot_user, review the permission request and arguments in Claude Code before approval.

Inspect the bot identity associated with the token.

notion_retrieve_database

For Notion's notion_retrieve_database, review the permission request and arguments in Claude Code before approval.

notion_create_database

For Notion's notion_create_database, review the permission request and arguments in Claude Code before approval.

notion_create_data_source

For Notion's notion_create_data_source, review the permission request and arguments in Claude Code before approval.

notion_query_data_source

For Notion's notion_query_data_source, review the permission request and arguments in Claude Code before approval.

notion_query_data_source_by_values

For Notion's notion_query_data_source_by_values, review the permission request and arguments in Claude Code before approval.

notion_retrieve_data_source

For Notion's notion_retrieve_data_source, review the permission request and arguments in Claude Code before approval.

notion_update_data_source

For Notion's notion_update_data_source, review the permission request and arguments in Claude Code before approval.

notion_create_data_source_item

For Notion's notion_create_data_source_item, review the permission request and arguments in Claude Code before approval.

Create a page item using a data source as parent.

notion_create_data_source_item_from_values

For Notion's notion_create_data_source_item_from_values, review the permission request and arguments in Claude Code before approval.

Create an item by converting simple values against the data source schema.

notion_create_comment

For Notion's notion_create_comment, review the permission request and arguments in Claude Code before approval.

Add a comment to a page or discussion with the required integration capability.

notion_retrieve_comments

For Notion's notion_retrieve_comments, review the permission request and arguments in Claude Code before approval.

Read unresolved comments with the required comment capability.

notion_find

For Notion's notion_find, review the permission request and arguments in Claude Code before approval.

Discover candidate pages or data sources with compact results and suggested follow-up tools.

notion_inspect_data_source

For Notion's notion_inspect_data_source, review the permission request and arguments in Claude Code before approval.

Summarize schema properties, options, and relation targets for an agent.

notion_search

For Notion's notion_search, review the permission request and arguments in Claude Code before approval.

Search for pages or data sources by title.

Notion: full stored tool descriptions

Troubleshooting Notion in Claude Code

• If Notion MCP Server fails to start, check npx @suekou/mcp-notion-server (Node.js/npm), the working directory, and Claude Code's selected scope; inspect claude mcp list and /mcp.
• Notion MCP Server: check NOTION_API_TOKEN; keep credentials out of shared .mcp.json.
• Notion MCP Server uses stdio here: Claude Code 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 Code troubleshooting lives in the /clients/claude-code guide.

Frequently asked questions