Notion MCP Server

How to use

You run the MCP server locally and connect your MCP client to it. Use the stdio transport for traditional desktop clients or enable the streamable HTTP transport for web-based clients. Configure your client with either a Notion access token or a prebuilt header set so the MCP server can authenticate against Notion.

How to install

Prerequisites you need before getting started: a working Node.js/npm installation, or Docker if you choose containerized runs. You should also have a Notion integration token ready if you plan to authenticate with Notion directly.

Notion MCP Server configurations

The server can be started via a local runtime (stdio transport) or via Docker. The following configurations are directly derived from the available setup options.

Notion MCP Server with npm/npx (stdio transport)

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

Notion MCP Server with npm/npx using OPENAPI_MCP_HEADERS (stdio transport)

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2022-06-28\" }"
      }
    }
  }
}

Notion MCP Server with Docker (stdio transport)

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": ["run","--rm","-i","-e","NOTION_TOKEN","mcp/notion"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

Notion MCP Server with Docker using OPENAPI_MCP_HEADERS (stdio transport)

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": ["run","--rm","-i","-e","OPENAPI_MCP_HEADERS","mcp/notion"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2022-06-28\" }"
      }
    }
  }
}

Building and running locally with Docker image

docker compose build
```
```javascript
{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "NOTION_TOKEN=ntn_****",
        "notion-mcp-server"
      ]
    }
  }
}

Transport overview and authentication

The MCP server supports two transport modes: stdio (default) and Streamable HTTP. The stdio transport is suitable for desktop clients, while HTTP can be used by web-based clients with bearer token authentication. For HTTP, either auto-generated tokens or a custom token can be used via command line or environment variables.

Examples of common usage patterns

You can plan to access and manipulate Notion content through your AI flows by configuring the MCP client with the appropriate authentication header and pointing it to the local MCP server process. Ensure you have a valid Notion integration token and that the pages or databases you want to access are connected to that integration.

Development tips

If you prefer a local build/run flow, use a containerized approach with Docker, or run the MCP server through npx for quick experimentation. Always provide the correct authentication tokens and Notion-Version headers as shown in the configuration examples.