Set Up the Notion MCP Server

The Notion MCP server connects AI agents to your Notion workspace, acting as an automated librarian. It enables your agents to search across documentation, read tabular databases, and create or append new content directly to your pages without you leaving your chat interface.

Prerequisites

• ▸A Notion account with workspace-level access.
• ▸A Notion API Integration Token.
• ▸Node.js 18+ installed on your host machine.

Creating a Notion Integration

1. ▸Go to notion.so/my-integrations.
2. ▸Click New integration.
3. ▸Name it (e.g., "MCP AI Agent") and select your target workspace.
4. ▸Set capabilities: Read content, Update content, Insert content.
5. ▸Save and copy the Internal Integration Token.

Sharing Pages with the Integration

[!IMPORTANT] Your integration token has zero access by default. You must explicitly share pages and databases with your integration before the MCP server can see them.

1. ▸Open the page or database in Notion.
2. ▸Click Share (top right corner).
3. ▸Search for your integration name (e.g., "MCP AI Agent").
4. ▸Click Invite. (Tip: Sharing a parent page automatically cascades access to all nested sub-pages!)

Configuration Setup

Add the following to your MCP client config file:

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

Available Tools

Once running, your agent gains access to:

• ▸search_pages — Search across all shared pages using semantic keywords.
• ▸get_page — Retrieve a specific page's content as Markdown.
• ▸create_page — Create brand new Notion pages.
• ▸update_page — Modify existing page blocks.
• ▸query_database — Query Notion databases with complex property filters.
• ▸create_database_item — Add rows to Notion databases.

Example Workflows

• ▸Meeting Notes Summary: "Search my Notion for all meeting notes from this week, summarize the action items, and create a new page titled 'Weekly Digest'."
• ▸Project Tracking: "Query my 'Engineering Projects' database for all items with the status 'In Progress' and list their due dates."
• ▸Documentation Retrieval: "Search my Notion for any documentation about our staging deployment process and explain it to me."

Troubleshooting

• ▸Page Not Found Error: The agent tried to read a page ID that hasn't been shared with the integration. Go into Notion and manually share the page.
• ▸429 Too Many Requests: Notion has strict rate limits (averaging 3 requests per second). If the agent attempts to fetch too many pages simultaneously, it will hit a rate limit. Instruct the agent to add slight delays between tool calls.

Using with OpenAI Codex

You can use this MCP server with the OpenAI Codex CLI by adding it to your configuration:

codex mcp add --name notion --command "npx -y @modelcontextprotocol/server-notion" --env NOTION_API_KEY=your_integration_token

For a full list of recommended servers, see Best MCP Servers for OpenAI Codex.