Notion MCP Server for Windsurf: Setup & Config

What you can do with Notion in Windsurf

Choose it for local Notion API access with scoped integrations and Markdown page tools.

• Read page content as Markdown for an AI workflow.
• Inspect database metadata and data source schemas.

Before you start: Notion in Windsurf

• A Notion internal integration
• Access granted to the relevant pages or databases
• An MCP-compatible client
• npx for the npm launch method

This configuration launches the local stdio server. HTTP and Docker alternatives are documented. Notion prioritizes support for its separate remote service.

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 notion-mcp-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": {
    "notion-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@notionhq/notion-mcp-server"
      ],
      "env": {
        "NOTION_TOKEN": "<Notion internal integration token>"
      }
    }
  }
}

Notion tools available to Windsurf

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

query-data-source

After refreshing Notion in Windsurf settings, check Cascade's tool list for query-data-source.

Search a data source using filters and sort rules.

retrieve-a-data-source

After refreshing Notion in Windsurf settings, check Cascade's tool list for retrieve-a-data-source.

Read a data source schema and metadata.

update-a-data-source

After refreshing Notion in Windsurf settings, check Cascade's tool list for update-a-data-source.

create-a-data-source

After refreshing Notion in Windsurf settings, check Cascade's tool list for create-a-data-source.

list-data-source-templates

After refreshing Notion in Windsurf settings, check Cascade's tool list for list-data-source-templates.

Find templates available within a data source.

move-page

After refreshing Notion in Windsurf settings, check Cascade's tool list for move-page.

retrieve-a-database

After refreshing Notion in Windsurf settings, check Cascade's tool list for retrieve-a-database.

retrieve-page-markdown

After refreshing Notion in Windsurf settings, check Cascade's tool list for retrieve-page-markdown.

Fetch page content as Markdown, optionally including meeting transcripts.

update-page-markdown

After refreshing Notion in Windsurf settings, check Cascade's tool list for update-page-markdown.

Replace page Markdown or apply targeted text changes.

Notion: full stored tool descriptions

Troubleshooting Notion in Windsurf

• Check npx @notionhq/notion-mcp-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_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: The local repository no longer receives active issue and pull request monitoring.
• Known limitation: Upgrading can require changes to hardcoded database tool names.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions