setup-notion

Setup Notion

Purpose

Configure Notion's official hosted MCP for this project, help the user complete browser OAuth, and verify the intended workspace before any content is created.

Current supported path

• Official endpoint: https://mcp.notion.com/mcp
• Transport: remote HTTP
• Authentication: OAuth in the browser
• Project configuration: .mcp.json

Notion's hosted MCP does not currently support file uploads. Do not promise that a local chart or other file can be uploaded through this server. Create the text page first. If the user needs an attachment, they can add it manually or use a separately approved API workflow.

Instructions

1. Inspect before changing configuration

1. Read .mcp.json if it exists.
2. Preserve every existing MCP server.
3. Check whether a Notion server already points to the official endpoint.
4. If Notion tools are already available, skip configuration and verify the connection.
5. Before editing anything, show the user the exact non-secret change and ask for approval.

Never replace the entire MCP configuration merely to add Notion.

2. Add the official server

After approval, add this project-local server entry while preserving the rest of .mcp.json:

{
  "notion": {
    "type": "http",
    "url": "https://mcp.notion.com/mcp"
  }
}

An equivalent supported Claude Code command is:

claude mcp add --transport http --scope project notion https://mcp.notion.com/mcp

Do not put tokens or credentials in the configuration.

3. Authenticate

If this session did not load the new server, tell the user to restart Claude Code. Then have the user run /mcp, select Notion, and complete OAuth in the browser.

Before the user authorizes access, remind them to confirm:

• the Notion account;
• the workspace;
• whether that workspace is approved for the intended work; and
• that the connected client can act with the access granted to that user.

Do not claim that OAuth proves the destination or makes every future action safe.