How to add Notion MCP Server (official) to Windsurf

Official Notion server to read, search, create, and update pages and databases in your workspace. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 15, 2026 · 3.9k★ · stdio · apikey · official

Windsurf config for Notion MCP Server (official)

npx -y @notionhq/notion-mcp-server

{
  "mcpServers": {
    "notion-mcp-server-official": {
      "command": "npx",
      "args": [
        "-y",
        "@notionhq/notion-mcp-server"
      ],
      "env": {
        "NOTION_TOKEN": "<your-notion-integration-token>"
      }
    }
  }
}

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the Notion MCP Server (official) config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5Notion MCP Server (official)'s tools become available to Cascade.

Before you start

Node.js (a current LTS, Node 18+; run via npx without a global install)
A Notion internal integration token (an 'Internal Integration Secret') created at https://www.notion.so/profile/integrations
Each page/database the agent should touch must be shared with the integration (via the page's Connections menu or the integration's Access tab)
Optional: Docker if you prefer the mcp/notion image instead of npx

What Notion MCP Server (official) can do in Windsurf

search

Search across pages and databases in the workspace

retrieve-a-page / create-a-page / update-a-page / move-page

Read, create, update, and move pages

query-data-source

Query a database/data source with filters and sorts

retrieve-a-data-source / create-a-data-source / update-a-data-source

Read and manage database (data source) schemas

retrieve-a-database

Retrieve a database object

append-block-children / retrieve-block-children

Read and append child blocks within a page

update-block / delete-a-block

Edit or delete individual content blocks

retrieve-comments / create-a-comment / update-a-comment / delete-a-comment

Read and manage page comments

Security

The integration token grants API access only to pages and databases you explicitly share with it, so scope access narrowly. Store NOTION_TOKEN as an env var, never in committed config.

Notion MCP Server (official) + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Notion MCP Server (official) config there under the "mcpServers" key and restart the client.

Is Notion MCP Server (official) safe to use with Windsurf?

The integration token grants API access only to pages and databases you explicitly share with it, so scope access narrowly. Store NOTION_TOKEN as an env var, never in committed config.

Why do the tools return nothing / 'object not found'?

The integration can only see pages and databases explicitly shared with it. Open the target page's Connections menu (or the integration's Access tab) and add the integration.

How do I provide the token?

Set the NOTION_TOKEN environment variable to your integration's internal secret (recommended). An advanced OPENAPI_MCP_HEADERS variable also exists for passing custom Authorization and Notion-Version headers.

Is there a hosted/remote version?

Yes. Notion offers a remote MCP server at mcp.notion.com with OAuth-based setup and Notion-optimized tools; Notion is prioritizing it and may reduce support for this local repo.

View repo Full Notion MCP Server (official) page