Notion MCP

npx add-mcp 'https://mcp.notion.com/mcp'

Notion MCP 伺服器

[!NOTE]

為獲得最佳體驗，請使用 遠端 Notion MCP， 這是我們官方代管的 MCP 伺服器。本儲存庫是另一個自行代管的 MCP 伺服器實作，已不再積極維護或支援。請改用遠端 Notion MCP。 它是專為讓 AI 代理程式 以更少的 token 獲得更快的結果 而設計。

遠端 Notion MCP 可以語意化搜尋你的工作空間和已連接的應用程式、以 Markdown 讀取和 編輯頁面，並只回傳最相關的內容。這代表更少的等待時間、更少的 context-window 使用量， 以及更低的 token 成本。它也使用 OAuth，並自動尊重每位使用者既有的 Notion 權限——無需 API token、JSON 設定、手動分享頁面，或維護本機伺服器。

功能	遠端 Notion MCP	本專案（本機）
快速、代管的體驗	✅	在本機執行與更新
節省 token 的回應	✅	有限
專為 AI 代理程式打造的高效能工具	✅	基本的 API 衍生工具
在 Notion 工作空間中進行語意化搜尋	✅	僅限關鍵字搜尋
跨已連接應用程式的 AI Connector 搜尋	✅	不適用
以 Markdown 原生讀取和編輯頁面	✅	僅限兩個頁面內容工具
無縫的 OAuth 設定	✅	手動 token 和 JSON 設定
尊重每位使用者既有的 Notion 權限	✅	手動整合權限和頁面分享
積極支援與持續改進	✅	未積極支援

在 遠端 Notion MCP 文件 中了解更多並開始使用。

我們優先考量，且僅對 遠端 Notion MCP 提供積極支援。因此：

• 我們未來可能會停止此本機 MCP 伺服器儲存庫。
• 此處的 issue 和 pull request 不會被積極監控。
• 請勿在此處提交與遠端 MCP 相關的 issue；請改為聯絡 Notion 支援。

此專案為 Notion API 實作了一個 MCP 伺服器。

---

⚠️ 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-query	query-data-source	database_id → data_source_id
update-a-database	update-a-data-source	database_id → data_source_id
create-a-database	create-a-data-source	無變更（使用 parent.page_id）

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

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

---

頁面內容作為 Markdown

伺服器提供兩個工具，用於將頁面內容作為增強型 Markdown（而非區塊 JSON）處理，這對 AI 代理程式來說在 token 使用上更有效率：

• 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 並建立一個新的內部整合，或選擇一個現有的整合。

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

例如，你可以透過僅在「Configuration」分頁中給予「Read content」存取權限來建立唯讀整合 token：

2. 將內容連接到整合

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

為此，請造訪內部整合設定中的 Access 分頁。編輯存取權限並選擇你想使用的頁面。

或者，你也可以個別授予頁面存取權限。你需要造訪目標頁面，點擊右上角的 3 個點，然後選擇「Connect to integration」。

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_**** 替換為你的整合密鑰。你可以在整合設定分頁中找到它：

傳輸選項

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

Streamable HTTP 傳輸

對於基於 Web 的應用程式或偏好 HTTP 通訊的用戶端，你可以使用 Streamable 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"

使用 Streamable HTTP 傳輸時，伺服器預設將在 http://127.0.0.1:<port>/mcp 提供服務。

驗證

Streamable HTTP 傳輸出於安全考量需要 bearer token 驗證。你有三個選項：

選項 1：自動產生的 token（僅供開發使用）

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

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

Generated auth token written to: /tmp/.notion-mcp-auth-token-12345

選項 2：透過命令列使用自訂 token（建議用於生產環境）

npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"

選項 3：透過環境變數使用自訂 token（建議用於生產環境）

AUTH_TOKEN="your-secret-token" npx @notionhq/notion-mcp-server --transport http

如果同時提供兩者，命令列參數 --auth-token 的優先順序高於 AUTH_TOKEN 環境變數。

不安全的選項：停用 HTTP 驗證

你只能使用明確的不安全旗標來停用 bearer token 驗證：

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

警告：--unsafe-disable-auth 是不安全的。伺服器可能透過 DNS rebinding 被你造訪的頁面觸及。請僅在隔離的網路上使用它。

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

發出 HTTP 請求

對 Streamable HTTP 傳輸的所有請求都必須在 Authorization 標頭中包含 bearer token：

# 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 整合 token。

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

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

# 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 token：

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

每個連線的 token 解析方式，依序為：

1. Notion-Token 標頭（建議——無歧義，且可與伺服器自身的 Authorization 閘道驗證並存）。如果存在，則必須是有效的 Notion token，否則請求將以 401 拒絕。
2. Authorization: Bearer ntn_**** — 僅在伺服器自身的 bearer 驗證關閉時（--unsafe-disable-auth），因此標頭可以自由地直接攜帶 Notion token。
3. 否則使用啟動時的環境變數 token（NOTION_TOKEN / OPENAPI_MCP_HEADERS）（如果已設定），因此傳遞和預設整合可以在同一個部署上共存。

注意事項：

• 只有具有 Notion token 前綴（ntn_、舊版 secret_）的值才會被視為 Notion token，因此伺服器的閘道密鑰和租戶的 Notion token 永遠不會衝突。
• 每個 token 都綁定到其 MCP 工作階段；token 永遠不會被記錄（只會輸出經過遮罩的前綴）。
• 這是一個刻意的 token 傳遞設定。請務必透過 TLS 部署，並偏好保持伺服器自身的 bearer 驗證（--auth-token）啟用，作為多租戶流量前方的閘道。

範例

1. 使用以下指令

Comment "Hello MCP" on page "Getting started"

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

1. 同樣地，以下指令將產生一個名為「Notion MCP」的新頁面，並新增到父頁面「Development」中

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