Notion MCP

官方

官方 Notion MCP 伺服器，供 AI 代理搜尋、讀取、建立及更新 Notion 頁面、資料庫與工作區內容。

GitHub
4.5k

你可以用 Notion MCP 做什麼？

  • 依標題搜尋頁面或資料來源 — 使用 post-search 依名稱在工作區中尋找頁面與資料來源。
  • 以 Markdown 讀取頁面內容 — 透過 retrieve-page-markdown 擷取頁面的完整內容，可選擇包含會議逐字稿。
  • 以 Markdown 編輯頁面內容 — 使用 update-page-markdown 覆寫或尋找並取代頁面內容。
  • 使用篩選與排序查詢資料來源 — 透過 query-data-source 對資料來源執行結構化查詢。
  • 在上層頁面或資料來源內建立新頁面 — 使用 post-page 新增頁面，並指定 page_id 或 database_id 作為上層。
  • 將頁面移至不同的上層位置 — 透過 move-page 移動頁面來重新整理工作區。

文件

Notion MCP 伺服器

[!NOTE]

我們推出了 Notion MCP，一個遠端 MCP 伺服器，具備以下改進：

  • 透過標準 OAuth 輕鬆安裝。不再需要手動處理 JSON 或 API 權杖。
  • 專為 AI 代理設計的強大工具，包括以 Markdown 編輯頁面。這些工具在設計時已考量到最佳化的權杖消耗。

前往 Notion MCP 文件 了解更多並開始使用。

我們目前優先處理並僅對 Notion MCP（遠端）提供積極支援。因此：

  • 我們未來可能會淘汰這個本機 MCP 伺服器儲存庫。
  • 此處的議題和拉取請求不會被積極監控。
  • 請勿在此處提交與遠端 MCP 相關的議題；請改為聯絡 Notion 支援。

notion-mcp-sm

此專案實作了一個用於 Notion API 的 MCP 伺服器。

mcp-demo

⚠️ 版本 2.0.0 重大變更

版本 2.0.0 遷移至 Notion API 2025-09-03，該版本引入了資料來源作為資料庫的主要抽象層。

變更內容

已移除的工具 (3)：

  • post-database-query - 由 query-data-source 取代
  • update-a-database - 由 update-a-data-source 取代
  • create-a-database - 由 create-a-data-source 取代

新增工具 (7)：

  • query-data-source - 使用篩選和排序查詢資料來源（資料庫）
  • retrieve-a-data-source - 取得資料來源的中繼資料和結構描述
  • update-a-data-source - 更新資料來源屬性
  • create-a-data-source - 建立新的資料來源
  • list-data-source-templates - 列出資料來源中可用的範本
  • move-page - 將頁面移動到不同的父層位置
  • retrieve-a-database - 取得資料庫中繼資料，包括其資料來源 ID

參數變更：

  • 所有資料庫操作現在使用 data_source_id 而非 database_id
  • 搜尋篩選值從 ["page", "database"] 變更為 ["page", "data_source"]
  • 頁面建立現在支援 page_id 和 database_id 父層（用於資料來源）

我需要遷移嗎？

無需更改程式碼。 MCP 工具會在伺服器啟動時自動探索。當您升級到 v2.0.0 時，AI 客戶端會自動看到新的工具名稱和參數。舊的資料庫工具已不再可用。

如果您有硬編碼的工具名稱或提示參照了舊的資料庫工具，請更新它們以使用新的資料來源工具：

舊工具 (v1.x)新工具 (v2.0)參數變更
post-database-queryquery-data-sourcedatabase_id → data_source_id
update-a-databaseupdate-a-data-sourcedatabase_id → data_source_id
create-a-databasecreate-a-data-source無變更（使用 parent.page_id）

注意： retrieve-a-database 仍然可用，並會傳回資料庫中繼資料，包括資料來源 ID 清單。使用 retrieve-a-data-source 來取得特定資料來源的結構描述和屬性。

目前工具總數：22（v1.x 為 19）

以 Markdown 呈現的頁面內容

伺服器提供了兩個工具，用於將頁面內容作為增強的 Markdown 來處理，而非區塊 JSON，這對 AI 代理來說在權杖效率上顯著更高：

  • retrieve-page-markdown — 以 Markdown 讀取頁面的完整內容（GET /v1/pages/{page_id}/markdown）。傳遞 include_transcript: true 以內嵌會議記錄轉錄稿。
  • update-page-markdown — 使用 Markdown 編輯頁面內容（PATCH /v1/pages/{page_id}/markdown）。偏好使用 replace_content 來覆寫整個頁面，或使用 update_content 進行目標性的尋找與取代編輯。

這些端點需要 Notion API 版本 2026-03-11。伺服器現在會根據 OpenAPI 規格針對每個操作取得 Notion-Version 標頭，因此這些工具使用 2026-03-11，而其餘 API 則繼續使用 2025-09-03 — 無需設定。如果您透過 OPENAPI_MCP_HEADERS 自行設定了 Notion-Version，您的值將對每個工具具有優先權。

安裝

1. 在 Notion 中設定整合

前往 https://www.notion.so/profile/integrations 並建立一個新的內部整合，或選取現有的整合。

Creating a Notion Integration token

雖然我們限制了 Notion API 的公開範圍（例如，您將無法透過 MCP 刪除資料庫），但將工作區資料暴露給 LLM 仍存在非零風險。注重安全性的使用者可能希望進一步設定整合的 功能。

例如，您可以僅從「設定」分頁授予「讀取內容」存取權，以建立唯讀整合權杖：

Notion Integration Token Capabilities showing Read content checked

2. 將內容連結到整合

確保相關頁面和資料庫已連結到您的整合。

為此，請前往內部整合設定中的 存取 分頁。編輯存取權並選取您要使用的頁面。

Integration Access tab

Edit integration access

或者，您可以個別授予頁面存取權。您需要前往目標頁面，點擊 3 個點，然後選取「連結到整合」。

Adding Integration Token to Notion Connections

3. 將 MCP 設定新增到您的客戶端

使用 npm
Cursor 和 Claude

將以下內容新增到您的 .cursor/mcp.json 或 claude_desktop_config.json（MacOS：~/Library/Application\ Support/Claude/claude_desktop_config.json）

選項 1：使用 NOTION_TOKEN（建議）
{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}
選項 2：使用 OPENAPI_MCP_HEADERS（用於進階使用案例）
{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }"
      }
    }
  }
}
Zed

將以下內容新增到您的 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

使用 Copilot CLI 以互動方式新增 MCP 伺服器：

/mcp add

或者，建立或編輯設定檔 ~/.copilot/mcp-config.json 並新增：

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

如需更多資訊，請參閱 Copilot CLI 文件。

使用 Docker

使用 Docker 執行 MCP 伺服器有兩種選項：

選項 1：使用官方 Docker Hub 映像檔

將以下內容新增到您的 .cursor/mcp.json 或 claude_desktop_config.json

使用 NOTION_TOKEN（建議）：

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

使用 OPENAPI_MCP_HEADERS（用於進階使用案例）：

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

此方法：

  • 使用官方 Docker Hub 映像檔
  • 透過環境變數正確處理 JSON 跳脫
  • 提供更可靠的設定方式
選項 2：在本機建置 Docker 映像檔

您也可以在本機建置並執行 Docker 映像檔。首先，建置 Docker 映像檔：

docker compose build

然後，將以下內容新增到您的 .cursor/mcp.json 或 claude_desktop_config.json

使用 NOTION_TOKEN（建議）：

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

使用 OPENAPI_MCP_HEADERS（用於進階使用案例）：

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

別忘了將 ntn_**** 替換為您的整合密鑰。從您的整合設定分頁中找到它：

Copying your Integration token from the Configuration tab in the developer portal

傳輸選項

Notion MCP 伺服器支援兩種傳輸模式：

STDIO 傳輸（預設）

預設傳輸模式使用標準輸入/輸出進行通訊。這是大多數客戶端（如 Claude Desktop）使用的標準 MCP 傳輸方式。

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

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

可串流的 HTTP 傳輸

對於偏好 HTTP 通訊的網頁應用程式或客戶端，您可以使用可串流的 HTTP 傳輸：

# 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

# Bind to a different host. The default is 127.0.0.1.
npx @notionhq/notion-mcp-server --transport http --host 0.0.0.0

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

使用可串流的 HTTP 傳輸時，伺服器預設可在 http://127.0.0.1:<port>/mcp 上使用。

驗證

可串流的 HTTP 傳輸需要 Bearer 權杖驗證以確保安全性。您有三個選項：

選項 1：自動產生的權杖（僅供開發使用）
npx @notionhq/notion-mcp-server --transport http

伺服器將產生一個安全的隨機權杖，並將其寫入具有受限權限的檔案：

Generated auth token written to: /tmp/.notion-mcp-auth-token-12345
選項 2：透過命令列自訂權杖（建議用於生產環境）
npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"
選項 3：透過環境變數自訂權杖（建議用於生產環境）
AUTH_TOKEN="your-secret-token" npx @notionhq/notion-mcp-server --transport http

如果同時提供，命令列引數 --auth-token 的優先權高於 AUTH_TOKEN 環境變數。

不安全選項：停用 HTTP 驗證

您只能透過明確的不安全旗標來停用 Bearer 權杖驗證：

npx @notionhq/notion-mcp-server --transport http --unsafe-disable-auth

警告：--unsafe-disable-auth 是不安全的。伺服器可能會透過 DNS 重新綁定對您造訪的頁面開放存取。請僅在隔離的網路上使用。

當驗證停用時，伺服器會透過檢查 Host 和 Origin 標頭是否符合設定的本機主機和迴路主機來啟用 DNS 重新綁定保護。先前的 --disable-auth 旗標仍被接受為已棄用的別名，但會印出警告。

發出 HTTP 請求

所有對可串流 HTTP 傳輸的請求都必須在 Authorization 標頭中包含 Bearer 權杖：

# Example request
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

注意： 使用任一傳輸模式時，請確保設定 NOTION_TOKEN 環境變數（建議）或 OPENAPI_MCP_HEADERS 環境變數，並帶有您的 Notion 整合權杖。

服務多個整合（每個請求的權杖傳遞）

預設情況下，伺服器在啟動時使用單一權杖向 Notion 進行驗證，這會將一個部署鎖定到一個 Notion 整合。若要讓單一部署能服務多個整合，請啟用權杖傳遞，以便每個客戶端在每個連線中提供自己的 Notion 整合權杖：

# Enable per-request Notion tokens (flag or ENABLE_TOKEN_PASSTHROUGH=true)
npx @notionhq/notion-mcp-server --transport http --enable-token-passthrough

然後，客戶端在 initialize 請求中使用專用的 Notion-Token 標頭傳送其 Notion 權杖：

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

每個連線的權杖解析順序如下：

  1. Notion-Token 標頭（首選 — 明確無歧義，且可與伺服器自身的 Authorization 閘道驗證並存）。如果存在，它必須是有效的 Notion 權杖，否則請求會以 401 被拒絕。
  2. Authorization: Bearer ntn_**** — 僅當伺服器自身的 Bearer 驗證關閉時（--unsafe-disable-auth），此標頭才能直接用於攜帶 Notion 權杖。
  3. 否則，如果設定了啟動時的環境變數權杖（NOTION_TOKEN / OPENAPI_MCP_HEADERS），則使用該權杖，這樣權杖傳遞和預設整合可以在一個部署中共存。

注意事項：

  • 只有帶有 Notion 權杖前綴（ntn_、舊版 secret_）的值才會被視為 Notion 權杖，因此伺服器的閘道密鑰和租用戶的 Notion 權杖永遠不會衝突。
  • 每個權杖都綁定到其 MCP 工作階段；權杖絕不會被記錄（只會發出經過遮蔽的前綴）。
  • 這是一個經過深思熟慮的權杖傳遞設定。請務必透過 TLS 部署，並建議保持伺服器自身的 Bearer 驗證（--auth-token）啟用，作為多租用戶流量前的閘道。

範例

  1. 使用以下指令
Comment "Hello MCP" on page "Getting started"

AI 將正確規劃兩個 API 呼叫，v1/search 和 v1/comments，以完成任務

  1. 同樣地，以下指令將導致在父頁面「Development」中新增一個名為「Notion MCP」的頁面
Add a page titled "Notion MCP" to page "Development"
  1. 您也可以直接參照內容 ID
Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

開發

建置與測試

npm run build
npm test

執行

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

在 Cursor 中本機測試變更：

  1. 從儲存庫根目錄執行 npm link 命令，以建立指向 notion-mcp-server 套件的機器全域符號連結。
  2. 將下方的設定片段合併到 Cursor 的 mcp.json（或您想測試的其他 MCP 客戶端）中。
  3. （清理）從儲存庫根目錄執行 npm unlink。
{
  "mcpServers": {
    "notion-local-package": {
      "command": "notion-mcp-server",
      "env": {
        "NOTION_TOKEN": "ntn_..."
      }
    }
  }
}

發布

npm login
npm publish --access public