Notion MCP Server

You can install and configure the Notion MCP server using npx. Choose the configuration method based on your client.

Cursor & Claude

Add to .cursor/mcp.json or claude_desktop_config.json.

Option 1: Using NOTION_TOKEN (Recommended)

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

Option 2: Using OPENAPI_MCP_HEADERS (Advanced)

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

Zed

Add to settings.json:

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

GitHub Copilot CLI

Use /mcp add interactively, or edit ~/.copilot/mcp-config.json:

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

The Notion MCP Server supports two transport modes:

STDIO transport (default)

Used by most clients like Claude Desktop. Communication happens via standard input/output.

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

Streamable HTTP transport

Used for web-based applications. The server is available at http://127.0.0.1:<port>/mcp by default.

Common HTTP commands:

• Custom Port: --transport http --port 8080
• Custom Host: --transport http --host 0.0.0.0
• Custom Auth Token: --transport http --auth-token "your-secret-token" or via AUTH_TOKEN env var.
• Disable Auth (Unsafe): --transport http --unsafe-disable-auth (Use only on isolated networks; enables DNS rebinding protection).

Authentication for HTTP: All requests must include the bearer token in the Authorization header.

curl -H "Authorization: Bearer your-token-here" ... http://localhost:3000/mcp

npx @notionhq/notion-mcp-server --transport http --port 8080

To allow a single server deployment to serve multiple Notion integrations, enable token passthrough. This prevents the server from being locked to a single NOTION_TOKEN at startup.

1. Enable passthrough: Start the server with the --enable-token-passthrough flag or set ENABLE_TOKEN_PASSTHROUGH=true.

   npx @notionhq/notion-mcp-server --transport http --enable-token-passthrough

2. Client Request: Clients must send their specific Notion integration token in the Notion-Token header during the initialize request.

Token Resolution Order:

1. Notion-Token header (Preferred).
2. Authorization: Bearer ... (Only if server's own auth is disabled via --unsafe-disable-auth).
3. Startup environment variable (NOTION_TOKEN or OPENAPI_MCP_HEADERS).

curl -H "Authorization: Bearer <server-auth-token>" \
     -H "Notion-Token: ntn_****" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}' \
     http://localhost:3000/mcp

Version 2.0.0 migrates to the Notion API 2025-09-03, which shifts the primary abstraction for databases to data sources.

Tool Replacements

If you have hardcoded tool names or prompts, you must update them to the new tool names:

• Replace post-database-query with query-data-source.
• Replace update-a-database with update-a-data-source.
• Replace create-a-database with create-a-data-source.

Parameter Changes

• Database IDs: All database operations now require data_source_id instead of database_id.
• Search Filters: Search filter values have changed from ["page", "database"] to ["page", "data_source"].
• Page Creation: Supports both page_id and database_id as parents for data sources.

Migration Effort

Most AI clients will automatically discover the new tools upon server startup. No code changes are required unless you have hardcoded specific tool names or parameter keys in your prompts or logic.

Option 1: Using official Docker Hub image

Add to .cursor/mcp.json or claude_desktop_config.json.

Using NOTION_TOKEN (Recommended):

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

Using OPENAPI_MCP_HEADERS (Advanced):

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

Option 2: Building the Docker image locally

Build the image first:

docker compose build

Then add to client config (e.g., .cursor/mcp.json) using the local image name:

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