Notion MCP Server

How to use

You run the Notion MCP Server locally or remotely and connect an MCP client to it. The server exposes tools that let you query and manage Notion data sources, edit pages, and organize content. You can choose between a local (stdio) setup using a command line runtime or a containerized environment with Docker. When you start using it, your AI agents can perform actions like querying data sources, retrieving data source schemas, creating or updating data sources, and moving pages to new locations.

How to install

Prerequisites you need before installing: Node.js is commonly used to run MCP tooling via npx or npm, and Docker is available if you prefer containerized deployment.

Choose one of the following installation paths based on your preferred runtime environment.

Notion MCP Server stdio deployments

Use a local, stdio-based MCP server by invoking the package runner directly. You can pass environment variables to configure authentication.

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

Option 2: Use OPENAPI_MCP_HEADERS to provide a pre-authenticated header set for advanced use cases.

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

If you are using a Cursor/Claude integration, add the corresponding MCP config to your client config.

Notion MCP Server with Docker

Run the MCP server in Docker. Choose either a NOTION_TOKEN-based setup or an OPENAPI_MCP_HEADERS-based setup.

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

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

Security and access notes

When using the Notion MCP Server, you should limit integration capabilities to what you truly need. Notion API access can affect workspace data, so prefer read-only configurations when possible and grant access to only the necessary pages and databases.

Transport and authentication overview

Two transport modes are supported. The default stdio transport communicates over standard input/output. The Streamable HTTP transport exposes an HTTP API for clients that prefer HTTP, and supports token-based authentication.

For HTTP transport, you can start the server with an HTTP interface, specify a port, and pass an authentication token either via a command line flag or environment variable. The client must include the Bearer token in the Authorization header for requests.

Examples

Example usage patterns illustrate how to prompt the AI to interact with Notion pages and data sources, such as adding a page to a specific parent or tagging a page with a comment.

Development and testing

Build, test, and run locally following typical Node.js project workflows. You can run commands to build, test, and execute local MCP server instances as shown in the relevant steps.

Publish and maintenance notes

Community support for the local MCP server may vary. For remote Notion MCP, refer to the Notion support channels for guidance on issues and feature requests.

query-data-source

Query a data source with filters and sorts to retrieve data from a Notion database that is exposed as a data source in the MCP server.

retrieve-a-data-source

Get metadata and schema information for a specific data source to understand its structure and capabilities.

update-a-data-source

Update properties of an existing data source, such as its name, schema, or options.

create-a-data-source

Create a new data source (database) within the MCP server to start querying and managing data.

list-data-source-templates

List available templates for data sources to quickly set up common configurations.

move-page

Move a page to a different parent location within Notion to reorganize content.