Skip to main content
This guide walks you through connecting your AI tool to Notion using the Model Context Protocol (MCP). Once connected, your tool can read and write to your Notion workspace based on your access and permissions.

​
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.
  • --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.
For a richer experience, install the Notion plugin for Claude Code. It bundles the MCP server along with pre-built Skills and slash commands for common Notion workflows.

​
Cursor

1
Open Cursor Settings → MCP → Add new global MCP server
2
Paste the following configuration:
{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}
3
Save and restart Cursor. When you use a Notion tool for the first time, complete the OAuth flow to connect your workspace.
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)

1
Create a .vscode/mcp.json file in your workspace:
{
  "servers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    }
  }
}
2
Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) and run MCP: List Servers
3
Start the Notion server and complete the OAuth flow when prompted
To configure Notion MCP across all workspaces, run MCP: Open User Configuration from the Command Palette and add the server configuration there.

​
Claude Desktop

1
Open Settings → Connectors
2
Click Add Connector and enter the URL:
https://mcp.notion.com/mcp
3
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

1
Open Windsurf Settings (Cmd+, on Mac) → search for MCP
2
Click View raw config to open mcp_config.json
3
Add the Notion server configuration:
{
  "mcpServers": {
    "notion": {
      "serverUrl": "https://mcp.notion.com/mcp"
    }
  }
}
4
Save and restart Windsurf. Complete the OAuth flow when prompted.

​
ChatGPT

1
Go to chatgpt.com/#settings/Connectors (requires login)
2
Click Add Connector and enter the URL:
https://mcp.notion.com/mcp
3
Complete the OAuth flow to connect your Notion workspace

​
Other tools

If your AI tool isn’t listed above but supports MCP, you can connect using one of these URLs:
TransportURLNotes
Streamable HTTP (recommended)https://mcp.notion.com/mcpModern transport, widely supported
SSE (Server-Sent Events)https://mcp.notion.com/sseLegacy transport for older clients

​
JSON configuration format

Most MCP clients accept a JSON configuration. Use the appropriate format for your tool: 
{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}
Use the STDIO configuration if your tool doesn’t support remote HTTP connections directly.

​
Connect through the Notion app

As an alternative to configuring your AI tool directly, you can initiate the connection from within Notion:
1
Open Settings in the Notion app
2
Go to Connections → Notion MCP
3
Choose your AI tool from the list and complete the OAuth flow

​
Troubleshooting

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.
  • Make sure you complete the OAuth flow when prompted
  • Try disconnecting and reconnecting: look for a “Clear authentication” or “Disconnect” option in your tool’s MCP settings
  • Check that you have the correct permissions in the Notion workspace you’re trying to access
Check your tool’s documentation for how to add a remote MCP server. Most tools accept either a URL directly or a JSON configuration. If your tool doesn’t support MCP yet, consider reaching out to the developers to request MCP support.

​
FAQ

Notion MCP requires user-based OAuth authentication and does not support bearer token authentication. This means a user must complete the OAuth flow to authorize access, which may not be suitable for fully automated workflows or cloud-based coding agents that run without human interaction.If you need headless or fully automated access, you can use the open-source MCP server with a Notion API token, though this package is no longer actively maintained. Notion may explore supporting token-based authentication for remote MCP in the future.For security reasons, we recommend carefully reviewing actions performed by any MCP server before they’re executed.
Image and file uploads are not currently supported in Notion MCP, but this is on our roadmap. In the meantime, you can use the file upload API to upload files such as images and PDFs to your workspace.
Notion MCP (https://mcp.notion.com/mcp) is our hosted, actively maintained server. It uses OAuth for authentication, requires no infrastructure setup, and includes tools optimized for AI agents.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 integration and deployment.For most users, we recommend Notion MCP.
If you’re integrating Notion MCP into your own application or building a custom AI tool, see our MCP client integration guide for step-by-step instructions on implementing OAuth and connecting to Notion MCP.
What’s Next Learn what you can do with Notion MCP using the tools we provide: