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.

Codex (ChatGPT)

Codex is OpenAI’s coding agent. See the Codex MCP documentation for more details.

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.

Claude Code

Claude Code is Anthropic’s agentic coding tool for the terminal. See the Claude Code MCP documentation for more details. 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

Cursor is an AI code editor that can connect to MCP servers. See the Cursor MCP documentation for more details.

Create a .cursor/mcp.json file in your project root:

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

Open Customize in Cursor’s sidebar, then enable Notion and complete the OAuth flow to connect your workspace.

Global configuration

To configure Notion across all projects, add the same server configuration to ~/.cursor/mcp.json:

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

fx

fx is an MCP client that makes configured servers available in its interactive shell and agent sessions. See the fx MCP documentation for more details.

Start an interactive fx session:

fx

Add the Notion server:

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

In the same session, run /mcp auth notion --open and complete the OAuth flow.

JSON configuration

To configure Notion MCP without the CLI, add it to ~/.fx/mcp.json:

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

If a session is already open, run /mcp reload to pick up the change.

Hermes

Hermes is a coding agent from Nous Research that can be extended with MCP servers. See the Hermes MCP documentation for more details.

Add the Notion server to ~/.hermes/config.yaml:

mcp_servers:
  notion:
    url: "https://mcp.notion.com/mcp"
    auth: oauth

Authenticate by running:

hermes mcp login notion

Complete the OAuth flow to connect your Notion workspace.

Global configuration

The ~/.hermes/config.yaml configuration above applies to all projects for the current Hermes profile. See the Hermes configuration documentation for more details.

Devin

Devin is an AI software engineering agent that can connect to custom MCP servers. See the Devin MCP documentation for more details.

In Devin, go to Settings → Connections → MCP servers, then select Add a custom MCP.

Enter Notion as the server name, select HTTP as the transport, and set the server URL to:

https://mcp.notion.com/mcp

Select OAuth as the authentication method. Choose Personal access for an individual connection, or Organization access to share the connection with your organization.

Save the server, then complete the OAuth flow when Devin prompts you.

With Organization access, members share one authenticated connection. Use a Notion service account rather than a personal account, and have someone with the Manage MCP Servers permission complete the OAuth flow. With Personal access, each member authenticates their own Notion account.

Pi

Pi is an open-source, terminal-based coding agent. It uses the third-party Pi MCP Adapter to connect to MCP servers.

Install the adapter and restart Pi:

pi install npm:pi-mcp-adapter

In Pi, run /mcp setup, then choose Notion to add the server.

Authenticate by running /mcp-auth notion and completing the OAuth flow to connect your Notion workspace.

Global and team configuration

To use Notion in every Pi project, add this configuration to ~/.config/mcp/mcp.json. To share it with a team, commit the same configuration in a project-root .mcp.json; each teammate then completes the OAuth flow locally.

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

VS Code (GitHub Copilot)

Visual Studio Code supports MCP servers in its agent customization experience. See the VS Code MCP documentation for more details.

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.

Antigravity

Antigravity supports MCP servers across its products. See the Antigravity MCP documentation for more details. 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, add Notion as a remote MCP server:

Streamable HTTP (recommended): https://mcp.notion.com/mcp
SSE fallback: https://mcp.notion.com/sse — use this only if the client doesn’t support Streamable HTTP.

JSON configuration

If your client accepts a JSON configuration, start with Streamable HTTP:

{
  "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.

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

See Other MCP clients for the Notion MCP endpoints and JSON configuration examples. If the client doesn’t support MCP, contact its developer.

FAQs

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.

Get started

Agent APIs

API versions

Data APIs

Resources

Compliance

Link previews

Connect to Notion MCP

Codex (ChatGPT)

Claude Code

Cursor

fx

Hermes

Devin

Pi

VS Code (GitHub Copilot)

Antigravity

Other MCP clients

JSON configuration

Troubleshooting

FAQs

​Codex (ChatGPT)

​Claude Code

​Cursor

​fx

​Hermes

​Devin

​Pi

​VS Code (GitHub Copilot)

​Antigravity

​Other MCP clients

​JSON configuration

​Troubleshooting

​FAQs

Codex (ChatGPT)

Claude Code

Cursor

fx

Hermes

Devin

Pi

VS Code (GitHub Copilot)

Antigravity

Other MCP clients

JSON configuration

Troubleshooting

FAQs