Notion MCP

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

Máy chủ Notion MCP

[!NOTE]

Để có trải nghiệm tốt nhất, hãy sử dụng Remote Notion MCP, máy chủ MCP được lưu trữ chính thức của chúng tôi. Kho lưu trữ này là một bản triển khai máy chủ MCP tự lưu trữ riêng biệt, không còn được bảo trì hoặc hỗ trợ tích cực. Vui lòng sử dụng Remote Notion MCP để thay thế. Nó được thiết kế chuyên biệt để cung cấp cho các tác nhân AI kết quả nhanh hơn bằng cách sử dụng ít token hơn đáng kể.

Remote Notion MCP có thể tìm kiếm không gian làm việc và các ứng dụng được kết nối của bạn theo ngữ nghĩa, đọc và chỉnh sửa trang ở định dạng Markdown, đồng thời chỉ trả về ngữ cảnh phù hợp nhất. Điều đó có nghĩa là ít thời gian chờ đợi hơn, ít sử dụng cửa sổ ngữ cảnh hơn và chi phí token thấp hơn. Nó cũng sử dụng OAuth và tự động tôn trọng các quyền Notion hiện có của từng người dùng—mà không cần mã thông báo API, cấu hình JSON, chia sẻ trang thủ công hoặc máy chủ cục bộ để duy trì.

Tính năng	Remote Notion MCP	Dự án này (cục bộ)
Trải nghiệm nhanh, được lưu trữ	✅	Chạy và cập nhật cục bộ
Phản hồi tiết kiệm token	✅	Hạn chế
Các công cụ mạnh mẽ được thiết kế riêng cho tác nhân AI	✅	Các công cụ cơ bản dựa trên API
Tìm kiếm ngữ nghĩa trong không gian làm việc Notion của bạn	✅	Chỉ tìm kiếm từ khóa
Tìm kiếm AI Connector trên các ứng dụng được kết nối	✅	Không khả dụng
Đọc và chỉnh sửa trang gốc Markdown	✅	Giới hạn ở hai công cụ nội dung trang
Thiết lập OAuth liền mạch	✅	Cấu hình mã thông báo và JSON thủ công
Tôn trọng các quyền Notion hiện có của từng người dùng	✅	Quyền tích hợp thủ công và chia sẻ trang
Hỗ trợ tích cực và cải tiến liên tục	✅	Không được hỗ trợ tích cực

Tìm hiểu thêm và bắt đầu trong tài liệu Remote Notion MCP.

Chúng tôi đang ưu tiên và chỉ cung cấp hỗ trợ tích cực cho Remote Notion MCP. Do đó:

• Chúng tôi có thể ngừng cung cấp kho lưu trữ máy chủ MCP cục bộ này trong tương lai.
• Các vấn đề và yêu cầu kéo ở đây không được giám sát tích cực.
• Vui lòng không gửi vấn đề liên quan đến MCP từ xa tại đây; thay vào đó, hãy liên hệ với bộ phận hỗ trợ của Notion.

Dự án này triển khai một máy chủ MCP cho API Notion.

---

⚠️ Các thay đổi phá vỡ trong phiên bản 2.0.0

Phiên bản 2.0.0 chuyển sang API Notion 2025-09-03, giới thiệu nguồn dữ liệu (data sources) như là trừu tượng hóa chính cho cơ sở dữ liệu.

Điều gì đã thay đổi

Các công cụ bị xóa (3):

• post-database-query - được thay thế bởi query-data-source
• update-a-database - được thay thế bởi update-a-data-source
• create-a-database - được thay thế bởi create-a-data-source

Các công cụ mới (7):

• query-data-source - Truy vấn một nguồn dữ liệu (cơ sở dữ liệu) với bộ lọc và sắp xếp
• retrieve-a-data-source - Lấy siêu dữ liệu và lược đồ cho một nguồn dữ liệu
• update-a-data-source - Cập nhật các thuộc tính của nguồn dữ liệu
• create-a-data-source - Tạo một nguồn dữ liệu mới
• list-data-source-templates - Liệt kê các mẫu có sẵn trong một nguồn dữ liệu
• move-page - Di chuyển một trang đến vị trí cha khác
• retrieve-a-database - Lấy siêu dữ liệu cơ sở dữ liệu bao gồm các ID nguồn dữ liệu của nó

Các thay đổi về tham số:

• Tất cả các thao tác cơ sở dữ liệu hiện sử dụng data_source_id thay vì database_id
• Các giá trị bộ lọc tìm kiếm đã thay đổi từ ["page", "database"] thành ["page", "data_source"]
• Việc tạo trang hiện hỗ trợ cả cha page_id và database_id (cho nguồn dữ liệu)

Tôi có cần di chuyển không?

Không cần thay đổi mã. Các công cụ MCP được tự động phát hiện khi máy chủ khởi động. Khi bạn nâng cấp lên v2.0.0, các máy khách AI sẽ tự động thấy các tên công cụ và tham số mới. Các công cụ cơ sở dữ liệu cũ không còn khả dụng.

Nếu bạn có tên công cụ hoặc lời nhắc được mã hóa cứng tham chiếu đến các công cụ cơ sở dữ liệu cũ, hãy cập nhật chúng để sử dụng các công cụ nguồn dữ liệu mới:

Công cụ cũ (v1.x)	Công cụ mới (v2.0)	Thay đổi tham số
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	Không thay đổi (sử dụng parent.page_id)

Lưu ý: retrieve-a-database vẫn khả dụng và trả về siêu dữ liệu cơ sở dữ liệu bao gồm danh sách các ID nguồn dữ liệu. Sử dụng retrieve-a-data-source để lấy lược đồ và thuộc tính của một nguồn dữ liệu cụ thể.

Tổng số công cụ hiện tại: 22 (trước đây là 19 trong v1.x)

---

Nội dung trang dưới dạng Markdown

Máy chủ cung cấp hai công cụ để làm việc với nội dung trang dưới dạng Markdown nâng cao thay vì JSON khối, điều này tiết kiệm token đáng kể hơn cho các tác nhân AI:

• retrieve-page-markdown — Đọc toàn bộ nội dung của một trang dưới dạng Markdown (GET /v1/pages/{page_id}/markdown). Truyền include_transcript: true để nội tuyến bản ghi chú cuộc họp.
• update-page-markdown — Chỉnh sửa nội dung của một trang bằng Markdown (PATCH /v1/pages/{page_id}/markdown). Ưu tiên replace_content để ghi đè toàn bộ trang, hoặc update_content cho các chỉnh sửa tìm và thay thế có mục tiêu.

Các điểm cuối này yêu cầu phiên bản API Notion 2026-03-11. Máy chủ hiện lấy tiêu đề Notion-Version theo từng thao tác từ đặc tả OpenAPI, vì vậy các công cụ này sử dụng 2026-03-11 trong khi phần còn lại của API tiếp tục sử dụng 2025-09-03 — không cần cấu hình. Nếu bạn tự đặt Notion-Version thông qua OPENAPI_MCP_HEADERS, giá trị của bạn sẽ được ưu tiên cho mọi công cụ.

---

Cài đặt

1. Thiết lập tích hợp trong Notion

Truy cập https://www.notion.so/profile/integrations và tạo một tích hợp nội bộ mới hoặc chọn một tích hợp hiện có.

Mặc dù chúng tôi giới hạn phạm vi tiếp xúc của API Notion (ví dụ: bạn sẽ không thể xóa cơ sở dữ liệu qua MCP), vẫn có rủi ro khác không đối với dữ liệu không gian làm việc khi tiếp xúc với LLM. Người dùng quan tâm đến bảo mật có thể muốn cấu hình thêm Khả năng (Capabilities) của Tích hợp.

Ví dụ: bạn có thể tạo mã thông báo tích hợp chỉ đọc bằng cách chỉ cấp quyền truy cập "Đọc nội dung" từ tab "Cấu hình":

2. Kết nối nội dung với tích hợp

Đảm bảo các trang và cơ sở dữ liệu có liên quan được kết nối với tích hợp của bạn.

Để thực hiện việc này, hãy truy cập tab Truy cập trong cài đặt tích hợp nội bộ của bạn. Chỉnh sửa quyền truy cập và chọn các trang bạn muốn sử dụng.

Ngoài ra, bạn có thể cấp quyền truy cập trang riêng lẻ. Bạn sẽ cần truy cập trang mục tiêu, nhấp vào 3 dấu chấm và chọn "Kết nối với tích hợp".

3. Thêm cấu hình MCP vào máy khách của bạn

Sử dụng npm

Cursor & Claude

Thêm nội dung sau vào .cursor/mcp.json hoặc claude_desktop_config.json của bạn (MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json)

Tùy chọn 1: Sử dụng NOTION_TOKEN (khuyến nghị)

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

Tùy chọn 2: Sử dụng OPENAPI_MCP_HEADERS (cho các trường hợp sử dụng nâng cao)

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

Zed

Thêm nội dung sau vào settings.json của bạn

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

Sử dụng Copilot CLI để thêm máy chủ MCP một cách tương tác:

/mcp add

Ngoài ra, hãy tạo hoặc chỉnh sửa tệp cấu hình ~/.copilot/mcp-config.json và thêm:

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

Để biết thêm thông tin, hãy xem tài liệu Copilot CLI.

Sử dụng Docker

Có hai tùy chọn để chạy máy chủ MCP với Docker:

Tùy chọn 1: Sử dụng hình ảnh Docker Hub chính thức

Thêm nội dung sau vào .cursor/mcp.json hoặc claude_desktop_config.json của bạn

Sử dụng NOTION_TOKEN (khuyến nghị):

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

Sử dụng OPENAPI_MCP_HEADERS (cho các trường hợp sử dụng nâng cao):

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

Cách tiếp cận này:

• Sử dụng hình ảnh Docker Hub chính thức
• Xử lý đúng cách việc thoát JSON qua các biến môi trường
• Cung cấp phương pháp cấu hình đáng tin cậy hơn

Tùy chọn 2: Xây dựng hình ảnh Docker cục bộ

Bạn cũng có thể xây dựng và chạy hình ảnh Docker cục bộ. Đầu tiên, hãy xây dựng hình ảnh Docker:

docker compose build

Sau đó, thêm nội dung sau vào .cursor/mcp.json hoặc claude_desktop_config.json của bạn

Sử dụng NOTION_TOKEN (khuyến nghị):

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

Sử dụng OPENAPI_MCP_HEADERS (cho các trường hợp sử dụng nâng cao):

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

Đừng quên thay thế ntn_**** bằng bí mật tích hợp của bạn. Tìm nó từ tab cấu hình tích hợp của bạn:

Các tùy chọn vận chuyển

Máy chủ Notion MCP hỗ trợ hai chế độ vận chuyển:

Vận chuyển STDIO (mặc định)

Chế độ vận chuyển mặc định sử dụng đầu vào/đầu ra tiêu chuẩn để giao tiếp. Đây là vận chuyển MCP tiêu chuẩn được hầu hết các máy khách như Claude Desktop sử dụng.

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

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

Vận chuyển HTTP có thể phát trực tuyến

Đối với các ứng dụng dựa trên web hoặc máy khách thích giao tiếp HTTP, bạn có thể sử dụng vận chuyển HTTP có thể phát trực tuyến:

# 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"

Khi sử dụng vận chuyển HTTP có thể phát trực tuyến, máy chủ sẽ khả dụng tại http://127.0.0.1:<port>/mcp theo mặc định.

Xác thực

Vận chuyển HTTP có thể phát trực tuyến yêu cầu xác thực mã thông báo bearer để bảo mật. Bạn có ba tùy chọn:

Tùy chọn 1: Mã thông báo tự động tạo (chỉ dành cho phát triển)

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

Máy chủ sẽ tạo một mã thông báo ngẫu nhiên an toàn và ghi nó vào một tệp với các quyền hạn chế:

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

Tùy chọn 2: Mã thông báo tùy chỉnh qua dòng lệnh (khuyến nghị cho sản xuất)

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

Tùy chọn 3: Mã thông báo tùy chỉnh qua biến môi trường (khuyến nghị cho sản xuất)

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

Đối số dòng lệnh --auth-token được ưu tiên hơn biến môi trường AUTH_TOKEN nếu cả hai được cung cấp.

Tùy chọn không an toàn: vô hiệu hóa xác thực HTTP

Bạn chỉ có thể vô hiệu hóa xác thực mã thông báo bearer với cờ không an toàn rõ ràng:

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

CẢNH BÁO: --unsafe-disable-auth không an toàn. Máy chủ có thể truy cập được từ các trang bạn truy cập thông qua DNS rebinding. Chỉ sử dụng nó trên mạng cô lập.

Khi xác thực bị vô hiệu hóa, máy chủ bật bảo vệ DNS rebinding bằng cách kiểm tra các tiêu đề Host và Origin so với máy chủ cục bộ được cấu hình và các máy chủ loopback. Cờ --disable-auth trước đó vẫn được chấp nhận như một bí danh không dùng nữa, nhưng nó sẽ in cảnh báo.

Thực hiện yêu cầu HTTP

Tất cả các yêu cầu đến vận chuyển HTTP có thể phát trực tuyến phải bao gồm mã thông báo bearer trong tiêu đề Ủy quyền:

# 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

Lưu ý: Đảm bảo đặt biến môi trường NOTION_TOKEN (khuyến nghị) hoặc biến môi trường OPENAPI_MCP_HEADERS với mã thông báo tích hợp Notion của bạn khi sử dụng một trong hai chế độ vận chuyển.

Phục vụ nhiều tích hợp (chuyển tiếp mã thông báo theo yêu cầu)

Theo mặc định, máy chủ xác thực với Notion bằng một mã thông báo duy nhất được nhúng tại thời điểm khởi động, khóa một triển khai vào một tích hợp Notion duy nhất. Để cho phép một triển khai duy nhất phục vụ nhiều tích hợp, hãy bật chuyển tiếp mã thông báo để mỗi máy khách cung cấp mã thông báo tích hợp Notion của riêng mình cho mỗi kết nối:

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

Sau đó, máy khách gửi mã thông báo Notion của họ trên yêu cầu khởi tạo bằng cách sử dụng tiêu đề chuyên dụng 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

Cách mã thông báo được giải quyết cho mỗi kết nối, theo thứ tự:

1. Tiêu đề Notion-Token (ưu tiên — rõ ràng và hoạt động cùng với xác thực cổng Authorization của chính máy chủ). Nếu có, nó phải là một mã thông báo Notion hợp lệ, nếu không yêu cầu sẽ bị từ chối với 401.
2. Authorization: Bearer ntn_**** — chỉ khi xác thực bearer của chính máy chủ bị tắt (--unsafe-disable-auth), để tiêu đề có thể tự do mang mã thông báo Notion trực tiếp.
3. Nếu không, mã thông báo env khởi động (NOTION_TOKEN / OPENAPI_MCP_HEADERS), nếu được đặt, để chuyển tiếp và tích hợp mặc định có thể cùng tồn tại trên một triển khai.

Ghi chú:

• Chỉ các giá trị có tiền tố mã thông báo Notion (ntn_, secret_ kế thừa) mới được coi là mã thông báo Notion, vì vậy bí mật cổng của máy chủ và mã thông báo Notion của người thuê không bao giờ xung đột.
• Mỗi mã thông báo được liên kết với phiên MCP của nó; mã thông báo không bao giờ được ghi nhật ký (chỉ một tiền tố được biên tập lại được phát ra).
• Đây là một thiết lập chuyển tiếp mã thông báo có chủ ý. Luôn triển khai nó qua TLS và ưu tiên giữ xác thực bearer của chính máy chủ (--auth-token) được bật như một cổng trước lưu lượng đa người thuê.

Ví dụ

1. Sử dụng hướng dẫn sau

Comment "Hello MCP" on page "Getting started"

AI sẽ lập kế hoạch chính xác hai lệnh gọi API, v1/search và v1/comments, để hoàn thành nhiệm vụ

1. Tương tự, hướng dẫn sau sẽ tạo một trang mới có tên "Notion MCP" được thêm vào trang cha "Development"

Add a page titled "Notion MCP" to page "Development"

1. Bạn cũng có thể tham chiếu trực tiếp ID nội dung

Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

Phát triển

Xây dựng & kiểm thử

npm run build
npm test

Thực thi

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

Kiểm thử các thay đổi cục bộ trong Cursor:

1. Chạy lệnh npm link từ thư mục gốc của kho lưu trữ để tạo liên kết tượng trưng (symlink) toàn máy tới gói notion-mcp-server.
2. Hợp nhất đoạn cấu hình bên dưới vào tệp mcp.json của Cursor (hoặc máy khách MCP khác mà bạn muốn kiểm thử).
3. (Dọn dẹp) chạy npm unlink từ thư mục gốc của kho lưu trữ.

{
  "mcpServers": {
    "notion-local-package": {
      "command": "notion-mcp-server",
      "env": {
        "NOTION_TOKEN": "ntn_..."
      }
    }
  }
}

Xuất bản

npm login
npm publish --access public