Notion

You can run a Notion MCP Server to bridge Notion content with an MCP client. It lets you issue Notion-related actions through a standardized MCP interface, enabling automated workflows and external tooling to read pages, add pages, or fetch content with a consistent protocol.

How to use

You connect your MCP client to the Notion MCP Server using one of the available runtime options. You can run the server locally via npx, or through Docker, and you can pair it with your Notion integration by providing the necessary access headers. Once running, your MCP client can request actions such as reading content, adding pages, or querying data from your Notion workspace.

How to install

Prerequisites you need before starting: Node.js and npm (for npx-based usage) and Docker (for containerized usage). Make sure you have an active Notion integration with the required capabilities and the integration token available.

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

Option 1. Run via the official Docker image. This approach handles JSON escaping correctly and provides a reliable configuration method.

{
  "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\"}"
      }
    }
  }
}

Option 2. Build and run the Docker image locally. First, build the image, then run it with the required header.

docker-compose build

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

Replace ntn_**** with your actual integration secret. You can find it in your Notion integration configuration.

Additional configuration and notes

Security-conscious users may want to restrict the Notion integration capabilities to read-only content by configuring the Integration’s Capabilities. For example, you can limit access to only read content from the Configuration tab.

Examples of common tasks you can accomplish with the MCP server include planning the necessary API calls to perform an action, adding a new page to a parent page, or retrieving the content of a specific page.

Development

Build the server code for development or production use.

npm run build

npx -y --prefix /path/to/local/notion-mcp-server @notionhq/notion-mcp-server

npm publish --access public

Troubleshooting

If your MCP client cannot connect, verify that the headers you provide include a valid Bearer token and Notion-Version, and confirm that the server container or process is running and reachable at the expected entry point.

Available tools

comment_on_page

Insert or append a comment on a specified Notion page as part of an automated workflow.

add_page

Create a new page under a specified parent page with a given title.

get_page_content

Retrieve the content of a Notion page by its identifier to feed downstream processes.