Connect to Notion MCP

Follow the instructions for your MCP client. After you authorize the connection, the client can read and update content that you can access in the selected Notion workspace.

Claude Code

Run this command in your terminal:

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

Then authenticate by running /mcp in Claude Code and following the OAuth flow.

Using --scope flag for different installation scopes

--scope local (default): Available only to you in the current project
--scope project: Shared with your team via .mcp.json file
--scope user: Available to you across all projects

Use the /mcp command to list and manage the MCP servers you have installed, and use the /context command to understand the context token usage of your current session, including the number of tokens used by each MCP server that’s enabled.

Install the Notion plugin for Claude Code to add the MCP server, Skills, and slash commands for common Notion workflows.

Cursor

Open Cursor Settings → MCP → Add new global MCP server

Paste the following configuration:

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

Save and restart Cursor. When you use a Notion tool for the first time, complete the OAuth flow to connect your workspace.

Project-level configuration

To share the Notion MCP configuration with your team, create a .cursor/mcp.json file in your project root:

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

VS Code (GitHub Copilot)

Create a .vscode/mcp.json file in your workspace:

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

Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) and run MCP: List Servers

Start the Notion server and complete the OAuth flow when prompted

User-level configuration

To configure Notion MCP across all workspaces, run MCP: Open User Configuration from the Command Palette and add the server configuration there.

Claude Desktop

Open Settings → Connectors

Select Add Connector and enter the URL:

https://mcp.notion.com/mcp

Complete the OAuth flow to connect your Notion workspace

Remote MCP servers in Claude Desktop are configured through Settings → Connectors, not the claude_desktop_config.json file. Available on Pro, Max, Team, and Enterprise plans.

Windsurf

Open Windsurf Settings (Cmd+, on Mac) → search for MCP

Select View raw config to open mcp_config.json

Add the Notion server configuration:

{
  "mcpServers": {
    "notion": {
      "serverUrl": "https://mcp.notion.com/mcp"
    }
  }
}

Save and restart Windsurf. Complete the OAuth flow when prompted.

ChatGPT

Go to chatgpt.com/#settings/Connectors (requires login)

Select Add Connector and enter the URL:

https://mcp.notion.com/mcp

Complete the OAuth flow to connect your Notion workspace

Codex

For more details, see the Codex MCP documentation.

Add the Notion server to your Codex configuration at ~/.codex/config.toml:

[mcp_servers.notion]
url = "https://mcp.notion.com/mcp"

Authenticate by running:

codex mcp login notion

Complete the OAuth flow to connect your Notion workspace.

Project-level configuration

To share the Notion MCP configuration with your team, create a .codex/config.toml file in your project root with the same server configuration.

Antigravity

We recommend connecting to Notion MCP as a custom server rather than using the pre-configured “Notion” connector in the Antigravity MCP gallery, which uses the deprecated notion-mcp-server package.

Follow the Antigravity instructions for connecting custom MCP servers and add the following to your mcp_config.json:

{
  "mcpServers": {
    "notion": {
      "serverUrl": "https://mcp.notion.com/mcp"
    }
  }
}

Save the configuration. Antigravity will prompt you to complete the OAuth flow to connect your Notion workspace.

Other MCP clients

If your MCP client isn’t listed above, use one of these URLs:

Transport	URL	Notes
Streamable HTTP (recommended)	`https://mcp.notion.com/mcp`	Recommended for new clients
SSE (Server-Sent Events)	`https://mcp.notion.com/sse`	For clients that don’t support Streamable HTTP

JSON configuration format

Most MCP clients accept a JSON configuration. Use the format supported by your client:

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

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

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.notion.com/mcp"]
    }
  }
}

Use the STDIO configuration if your client doesn’t support remote HTTP connections.

Connect through the Notion app

You can also start the connection from Notion:

Open Settings in the Notion app

Go to Connections → Notion MCP

Choose your MCP client from the list and complete the OAuth flow

Troubleshooting

My MCP client doesn't support remote MCP servers

Some MCP clients only support local stdio servers. You can still connect to Notion MCP using the mcp-remote bridge:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.notion.com/mcp"]
    }
  }
}

As a last resort, you can run our open-source MCP server locally, though this package is no longer actively maintained.

Authentication issues

Complete the OAuth flow when prompted.
Disconnect and reconnect the client. Look for Clear authentication or Disconnect in its MCP settings.
Check your permissions in the Notion workspace that you’re trying to access.

My MCP client isn't listed here

Check the client’s documentation for how to add a remote MCP server. Most MCP clients accept a URL or JSON configuration. If the client doesn’t support MCP, contact its developer.

FAQ

Can I use Notion MCP without interactive authorization?

Not yet. Notion MCP currently requires you to complete the OAuth authorization flow. We’re working on support for non-interactive authorization for automated workflows.

Does Notion MCP support file uploads?

Yes. Use the notion-create-file-upload tool to upload images and other files up to 20 MiB. Workspace file-size limits still apply.The tool returns a short-lived upload URL and the headers and form field that the MCP client must use to send the file. After the upload succeeds, pass the response’s suggested_markdown directly to notion-create-pages or notion-update-page, or include it on a separate line in notion-create-comment markdown to attach the file. For larger files, use the file upload API.

What's the difference between Notion MCP and the open-source server?

Notion MCP (https://mcp.notion.com/mcp) is our hosted, actively maintained server. It supports OAuth authorization and requires no infrastructure setup.The open-source server (notion-mcp-server) is no longer actively maintained. It supports bearer token authentication and the original JSON-based v1 APIs, which may be useful for automated workflows, but requires you to manage your own connection and deployment.For most users, we recommend Notion MCP.

I'm building my own MCP client

If you’re integrating Notion MCP into your own application, see Build an MCP client for Notion for OAuth and connection requirements.

Next steps

See the Notion MCP tools that a connected client can use.

Get started

Agent APIs

API versions

Data APIs

Resources

Compliance

Link previews

Connect to Notion MCP

Claude Code

Cursor

VS Code (GitHub Copilot)

Claude Desktop

Windsurf

ChatGPT

Codex

Antigravity

Other MCP clients

JSON configuration format

Connect through the Notion app

Troubleshooting

FAQ

Next steps

​Claude Code

​Cursor

​VS Code (GitHub Copilot)

​Claude Desktop

​Windsurf

​ChatGPT

​Codex

​Antigravity

​Other MCP clients

​JSON configuration format

​Connect through the Notion app

​Troubleshooting

​FAQ

​Next steps

Claude Code

Cursor

VS Code (GitHub Copilot)

Claude Desktop

Windsurf

ChatGPT

Codex

Antigravity

Other MCP clients

JSON configuration format

Connect through the Notion app

Troubleshooting

FAQ

Next steps