Notion MCP Server for Windsurf: Setup & Config

What you can do with Notion in Windsurf

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
• Use interactive Notion exploration and editing apps

Before you start: Notion in Windsurf

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

1. Choose Windsurf configuration scope

   For Notion MCP Server, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add Notion MCP Server to Windsurf

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

3. Check Notion MCP Server in Windsurf

   Notion MCP Server: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

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

Notion tools available to Windsurf

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

notion_open_data_source_app

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_open_data_source_app.

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

notion_open_page_workbench

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_open_page_workbench.

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

notion_append_block_children

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_append_block_children.

notion_append_content

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_append_content.

notion_append_markdown

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_append_markdown.

notion_update_content

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_update_content.

notion_update_content_batch

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_update_content_batch.

notion_retrieve_block

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_retrieve_block.

notion_retrieve_block_children

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_retrieve_block_children.

notion_delete_block

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_delete_block.

Remove a selected Notion block.

notion_update_block

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_update_block.

Replace selected block fields using the raw API shape.

notion_retrieve_page

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_retrieve_page.

Fetch page metadata from Notion.

notion_read_page

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_read_page.

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

notion_update_page_properties

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_update_page_properties.

Change properties on a page or database item.

notion_list_all_users

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_list_all_users.

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

notion_retrieve_user

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_retrieve_user.

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

notion_retrieve_bot_user

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_retrieve_bot_user.

notion_retrieve_database

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_retrieve_database.

notion_create_database

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_create_database.

notion_create_data_source

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_create_data_source.

notion_query_data_source

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_query_data_source.

notion_query_data_source_by_values

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_query_data_source_by_values.

notion_retrieve_data_source

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_retrieve_data_source.

notion_update_data_source

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_update_data_source.

notion_create_data_source_item

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_create_data_source_item.

Create a page item using a data source as parent.

notion_create_data_source_item_from_values

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_create_data_source_item_from_values.

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

notion_create_comment

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_create_comment.

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

notion_retrieve_comments

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_retrieve_comments.

Read unresolved comments with the required comment capability.

notion_find

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_find.

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

notion_inspect_data_source

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_inspect_data_source.

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

notion_search

After refreshing Notion in Windsurf settings, check Cascade's tool list for notion_search.

Search for pages or data sources by title.

Notion: full stored tool descriptions

Troubleshooting Notion in Windsurf

• Check npx @suekou/mcp-notion-server (Node.js/npm) on the machine running Windsurf's MCP integration for Notion MCP Server; refresh MCP and inspect Cascade's tools.
• Check NOTION_API_TOKEN for Notion MCP Server; do not bypass a Windsurf permission error with a broad administrator token.
• Notion MCP Server uses stdio here: Windsurf 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 Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions