Notion MCP

Notion MCP Server

[!NOTE]

Chúng tôi đã giới thiệu Notion MCP, một máy chủ MCP từ xa với những cải tiến sau:

• Cài đặt dễ dàng thông qua OAuth tiêu chuẩn. Không cần phải loay hoay với JSON hay token API nữa.
• Các công cụ mạnh mẽ được thiết kế riêng cho tác nhân AI, bao gồm chỉnh sửa trang bằng Markdown. Những công cụ này được thiết kế với mục tiêu tối ưu hóa lượng token tiêu thụ.

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

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

• Chúng tôi có thể ngừng phát triển 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 tại đây không được theo dõi 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 Notion API.

---

⚠️ Thay đổi đột phá của phiên bản 2.0.0

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

Những gì đã thay đổi

Các công cụ bị loại bỏ (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 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 metadata và lược đồ cho một nguồn dữ liệu
• update-a-data-source - Cập nhật thuộc tính nguồn dữ liệu
• create-a-data-source - Tạo 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 metadata cơ sở dữ liệu bao gồm ID nguồn dữ liệu của nó

Thay đổi 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
• Giá trị bộ lọc tìm kiếm thay đổi từ ["page", "database"] thành ["page", "data_source"]
• 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 ứng dụng khách AI sẽ tự động thấy 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ụ được mã hóa cứng hoặc lời nhắc 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ề metadata cơ sở dữ liệu bao gồm danh sách 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ể cho các tác nhân AI:

• retrieve-page-markdown — Đọc toàn bộ nội dung trang dưới dạng Markdown (GET /v1/pages/{page_id}/markdown). Truyền include_transcript: true để nội tuyến bản ghi cuộc họp.
• update-page-markdown — Chỉnh sửa nội dung 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 Notion API 2026-03-11. Máy chủ hiện lấy header Notion-Version cho mỗi 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 của Notion API được tiết lộ (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ết lộ nó cho 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 của Tích hợp.

Ví dụ: bạn có thể tạo token tích hợp chỉ đọc bằng cách chỉ cấp quyền "Đọ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 liên quan được kết nối với tích hợp của bạn.

Để làm điều 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 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 ứng dụng khách của bạn

Sử dụng npm

Cursor & Claude

Thêm phần 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 phần 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, 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 image Docker Hub chính thức

Thêm phần 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 image Docker Hub chính thức
• Xử lý đúng cách việc thoát JSON thông qua 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 image Docker cục bộ

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

docker compose build

Sau đó, thêm phần 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:

Tùy chọn truyền tải

Notion MCP Server hỗ trợ hai chế độ truyền tải:

Truyền tải STDIO (mặc định)

Chế độ truyền tải mặc định sử dụng đầu vào/đầu ra tiêu chuẩn để giao tiếp. Đây là truyền tải MCP tiêu chuẩn được hầu hết các ứng dụng 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

Truyền tải HTTP có thể truyền phát

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

# 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 truyền tải HTTP có thể truyền phát, máy chủ sẽ khả dụng tại http://127.0.0.1:<port>/mcp theo mặc định.

Xác thực

Truyền tải HTTP có thể truyền phát yêu cầu xác thực token bearer để bảo mật. Bạn có ba tùy chọn:

Tùy chọn 1: Token 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 token ngẫu nhiên an toàn và ghi nó vào một tệp với quyền hạn chế:

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

Tùy chọn 2: Token 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: Token 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 token 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 là không an toàn. Máy chủ có thể bị truy cập từ các trang bạn truy cập thông qua DNS rebinding. Chỉ sử dụng nó trên mạng cách ly.

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

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

Tất cả các yêu cầu đến truyền tải HTTP có thể truyền phát phải bao gồm token bearer trong header Authorization:

# 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 token tích hợp Notion của bạn khi sử dụng bất kỳ chế độ truyền tải nào.

Phục vụ nhiều tích hợp (chuyển tiếp token theo yêu cầu)

Theo mặc định, máy chủ xác thực với Notion bằng một token duy nhất được nhúng khi khởi động, điều này khóa một triển khai với một tích hợp Notion. Để cho phép một triển khai duy nhất phục vụ nhiều tích hợp, hãy kích hoạt chuyển tiếp token để mỗi ứng dụng khách cung cấp token tích hợp Notion riêng của 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 đó, ứng dụng khách gửi token Notion của họ trên yêu cầu initialize bằng cách sử dụng header Notion-Token chuyên dụng:

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 token được giải quyết cho mỗi kết nối, theo thứ tự:

1. Header Notion-Token (được ưu tiên — rõ ràng và hoạt động cùng với xác thực cổng Authorization của máy chủ). Nếu có, nó phải là token Notion hợp lệ, nếu không yêu cầu bị từ chối với 401.
2. Authorization: Bearer ntn_**** — chỉ khi xác thực bearer của máy chủ bị tắt (--unsafe-disable-auth), vì vậy header được tự do mang token Notion trực tiếp.
3. Nếu không, token môi trường 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ố token Notion (ntn_, kế thừa secret_) mới được coi là token Notion, vì vậy bí mật cổng của máy chủ và token Notion của người thuê không bao giờ xung đột.
• Mỗi token được liên kết với phiên MCP của nó; token không bao giờ được ghi nhật ký (chỉ tiền tố được biên tập lại được phát ra).
• Đây là thiết lập chuyển tiếp token có chủ ý. Luôn triển khai nó qua TLS và ưu tiên giữ xác thực bearer của máy chủ (--auth-token) được kích hoạ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ẽ dẫn đến 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 tra

npm run build
npm test

Thực thi

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

Kiểm tra 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 toàn cục máy đến gói notion-mcp-server.
2. Hợp nhất đoạn cấu hình bên dưới vào mcp.json của Cursor (hoặc ứng dụng khách MCP khác mà bạn muốn kiểm tra).
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