Notion

Notion MCP Server lets you access your Notion data and actions remotely through a concise MCP interface. It supports both a local, standard input/output (stdio) transport for direct clients and a Streamable HTTP transport for web-based clients, improving accessibility and token handling for AI-driven workflows.

How to use

Set up your client to connect to the MCP server using one of the available transport modes. Use the stdio transport for desktop or local tooling, or enable the HTTP transport for web-based clients. Ensure you have a Notion integration with appropriate permissions and your Notion token available to authorize requests.

How to install

Prerequisites: you should have Node.js and npm installed if you plan to run the server via Node tools. You also need Docker if you intend to run the server inside a container.

Choose one of the following installation methods and follow the steps exactly.

Notion MCP server via stdio (local runtime)

Run the MCP server locally using a direct command with a package runner. This is the most common method for desktop clients.

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

Notion MCP server via stdio (advanced headers)

If you need to supply custom headers for advanced use cases, you can pass OPENAPI_MCP_HEADERS instead of NOTION_TOKEN.

{
  "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 via stdio (Docker)

Run the server inside Docker using the official image. This option keeps dependencies isolated.

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

Notion MCP server via Docker advanced (header-based)

For advanced setups using header-based authentication with Docker, use the OPENAPI_MCP_HEADERS environment variable.

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

Notion MCP server via Docker local build

If you prefer building the image locally, build the Docker image first and then run the container.

docker compose build

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

Smithery installation

Install the Notion MCP Server for Claude Desktop automatically using Smithery.

npx -y @smithery/cli install @makenotion/notion-mcp-server --client claude

Transport options

This server supports two transport modes: stdio for direct clients and Streamable HTTP for web-based clients. You choose the transport at startup or via your client configuration.

STDIO Transport (Default) lets you communicate using standard input/output, which is compatible with most desktop clients.

Streamable HTTP Transport exposes an HTTP endpoint at the default port 3000, or a custom port when specified. Bearer token authentication is required.

Authentication and security

For HTTP transport, provide a bearer token in the Authorization header. You can generate a token automatically during startup or supply a fixed token via a command-line option or environment variable. Ensure your Notion integration token is configured with the minimum necessary permissions to reduce risk.

Examples

Use the server to perform typical Notion actions from an AI agent, such as searching content, creating pages, or updating blocks, depending on your integration permissions and the scope you configured.

Development

Build and publish cycles follow the standard workflow for this server side project. Build, then execute the server, and finally publish updates.