Notion MCP Server

How to use

You will start a local or remote MCP server and connect it to your MCP client. Use the server to query data sources, retrieve metadata, update properties, and create new data sources. You can also move pages between locations and list available data source templates. Your client will discover and use the MCP tools automatically when the server starts, so you only need to configure the connection details and authenticate with your Notion integration token.

How to install

Prerequisites: you need Node.js and npm or a compatible container runtime if you choose Docker.

1) Set up your Notion integration and connect content to it as described in the integration setup steps.

2) Add MCP config to your client. Choose one of the configuration approaches shown below.

3) Run the MCP server using the chosen transport (stdio for local development or HTTP for web-based clients). The HTTP transport defaults to port 3000 unless you specify otherwise.

Configuration for MCP clients

The following configuration snippets show how to connect a client to the Notion MCP Server using either the NOTION_TOKEN method or the advanced OPENAPI_MCP_HEADERS method. Each configuration uses the stdio transport (local) by default.

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

Alternative using advanced headers for MCP (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\" }"
      }
    }
  }
}

Using Docker to run the MCP server

You can run the MCP server in Docker using the official image. Choose between NOTION_TOKEN and OPENAPI_MCP_HEADERS approaches.

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

Transport options

The Notion MCP Server supports two transport modes: stdio (default) and Streamable HTTP transport.

StdIO transport is used by most clients and runs directly in your environment.

HTTP transport allows web-based clients to communicate over HTTP with optional authentication.

# Run with default stdio transport
npx @notionhq/notion-mcp-server

# Or explicitly specify stdio
npx @notionhq/notion-mcp-server --transport stdio
```

```bash
# Run with Streamable HTTP transport on port 3000 (default)
npx @notionhq/notion-mcp-server --transport http

# Run on a custom port
npx @notionhq/notion-mcp-server --transport http --port 8080

# Run with a custom authentication token
npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"

Making HTTP requests

All HTTP transport requests must include a bearer token in the Authorization header.

curl -H "Authorization: Bearer your-token-here" \
     -H "Content-Type: application/json" \
     -H "mcp-session-id: your-session-id" \
     -d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}' \
     http://localhost:3000/mcp

Examples

Examples illustrate how to perform common tasks like commenting on a page or creating a new page within a parent.

Comment "Hello MCP" on page "Getting started"
```
```
Add a page titled "Notion MCP" to page "Development"
```
```
Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

Security and access

Keep your Notion integration token secret. Use read-only configurations if you only need to fetch content, and restrict capabilities to minimize exposure.

Development and testing

Build and test the server locally, then execute and verify that the client can discover and use the available tools.

npm run build
npm test
```

```bash
# Run the local MCP server for testing
npx -y --prefix /path/to/local/notion-mcp-server @notionhq/notion-mcp-server

query-data-source

Query a data source with filters and sorts to retrieve matching records from a Notion database.

retrieve-a-data-source

Get metadata and schema for a data source, including its properties and structure.

update-a-data-source

Update properties of a data source, such as its name, schema, or access settings.

create-a-data-source

Create a new data source associated with a parent page to organize databases or similar structures.

list-data-source-templates

List available templates that can be applied to a data source.

move-page

Move a page to a different parent location within Notion.

retrieve-a-database

Get database metadata including its data source IDs for backward compatibility.