Notion MCP Server Setup for Codex & Claude | Search, Create, Update Pages

Notion MCP Server Setup and Configuration Guide

The Notion Model Context Protocol (MCP) server connects AI assistants—including Claude Desktop, Cursor, Windsurf, and OpenAI Codex CLI—directly to your Notion workspace. Once integrated, your AI agent can query tabular databases, search across documentation, create new pages, and append summaries without leaving your editor.

Integration requires minting an Internal Integration Token with fine-grained page capabilities, granting access to workspace parent pages, and registering the server binary in host configuration manifests.

Prerequisites

• ▸An active Notion account with workspace permission to create integrations.
• ▸A Notion Internal Integration Token (secret_... or ntn_...).
• ▸Node.js 18+ installed locally.

Step 1: Create an Internal Integration in Notion

1. ▸Navigate to the Notion Developers Portal (opens in a new tab).
2. ▸Click + New integration.
3. ▸Fill out the form:
   • ▸Associated workspace: Select your target workspace.
   • ▸Name: MCP Workspace Agent
   • ▸Type: Internal (do not select public unless building a multi-tenant OAuth app).
4. ▸Under Capabilities, verify the following checkboxes are enabled:
   • ▸Read content
   • ▸Update content
   • ▸Insert content
5. ▸Click Save and copy your Internal Integration Secret (secret_xxxxxxxxxxxxxxxxxxxxxxxx).

Step 2: Share Pages & Databases with Your Integration

Critical Rule: In Notion, integration tokens have zero access by default. An MCP server cannot see any page or database unless you explicitly share that page with your integration.

1. ▸Open the root Notion page or workspace database you want your AI agent to access.
2. ▸Click the ••• (Options) icon or Share button in the top right corner.
3. ▸Under Connections, click Add connections.
4. ▸Search for your integration name (MCP Workspace Agent) and select Confirm.
5. ▸Pro Tip: Sharing a top-level parent page automatically inherits access for all child sub-pages.

Step 3: Configure Your AI Client

Select your host environment below to copy the exact configuration template:

Claude Desktop (claude_desktop_config.json)

File path:

• ▸macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• ▸Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Cursor IDE (~/.cursor/mcp.json)

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

OpenAI Codex CLI (~/.codex/config.toml)

[mcp_servers.notion]
command = "npx"
args = ["-y", "@suekou/mcp-notion-server"]

  [mcp_servers.notion.env]
  NOTION_API_TOKEN = "secret_your_notion_token_here"

Or register via terminal command:

codex mcp add --name notion --command "npx -y @suekou/mcp-notion-server" --env NOTION_API_TOKEN=secret_your_token

Windsurf / Cascade (~/.codeium/windsurf/mcp_config.json)

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

Available Notion Tools

Troubleshooting Common Errors

1. "Object Not Found" or Empty Search Results

• ▸Symptom: search_pages returns an empty array, or get_page errors with Could not find page with ID.
• ▸Fix: Verify you shared the page with your connection in the Notion UI. The token cannot search unshared pages.

2. HTTP 401 Unauthorized

• ▸Symptom: Server crashes during handshake with 401 Unauthorized.
• ▸Fix: Double check that NOTION_API_TOKEN starts with secret_ or ntn_ and contains no accidental whitespace or quotation marks.

3. Rate Limiting (HTTP 429)

• ▸Symptom: Agent tool call pauses with rate limit headers.
• ▸Fix: The Notion API enforces an average limit of 3 requests per second per integration. Avoid asking your agent to recursively fetch hundreds of pages in a single loop.

Interactive Links & Tools

• ▸Notion Server Detail in Directory
• ▸Customize Notion in Visual Config Generator
• ▸Client Compatibility Matrix
• ▸Troubleshoot JSON-RPC Errors