Notion MCP

Notion MCP Server

[!NOTE]

เราได้เปิดตัว Notion MCP ซึ่งเป็นเซิร์ฟเวอร์ MCP ระยะไกลที่มีการปรับปรุงดังต่อไปนี้:

• ติดตั้งง่ายผ่าน OAuth มาตรฐาน ไม่ต้องยุ่งยากกับ JSON หรือ API tokens อีกต่อไป
• เครื่องมือทรงพลังที่ปรับแต่งมาสำหรับ AI agents รวมถึงการแก้ไขหน้าในรูปแบบ Markdown เครื่องมือเหล่านี้ออกแบบมาโดยคำนึงถึงการใช้ token อย่างมีประสิทธิภาพ

เรียนรู้เพิ่มเติมและเริ่มต้นใช้งานได้ที่ เอกสาร Notion MCP

เรากำลังให้ความสำคัญและสนับสนุนเฉพาะ Notion MCP (ระยะไกล) เท่านั้น ดังนั้น:

• เราอาจยุติการให้บริการ repository ของเซิร์ฟเวอร์ MCP แบบ local นี้ในอนาคต
• Issues และ pull requests ที่นี่ไม่ได้รับการตรวจสอบอย่างสม่ำเสมอ
• โปรดอย่ายื่น issues ที่เกี่ยวข้องกับ MCP ระยะไกลที่นี่ ให้ติดต่อฝ่ายสนับสนุนของ Notion แทน

โปรเจกต์นี้ใช้งาน MCP server สำหรับ Notion API

---

⚠️ การเปลี่ยนแปลงที่ส่งผลกระทบในเวอร์ชัน 2.0.0

เวอร์ชัน 2.0.0 ย้ายไปใช้ Notion API 2025-09-03 ซึ่งแนะนำ data sources เป็น abstraction หลักสำหรับฐานข้อมูล

สิ่งที่เปลี่ยนแปลง

เครื่องมือที่ถูกลบออก (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 - สืบค้น data source (ฐานข้อมูล) ด้วยตัวกรองและการเรียงลำดับ
• retrieve-a-data-source - รับข้อมูล metadata และ schema สำหรับ data source
• update-a-data-source - อัปเดตคุณสมบัติของ data source
• create-a-data-source - สร้าง data source ใหม่
• list-data-source-templates - แสดงรายการเทมเพลตที่มีใน data source
• move-page - ย้ายหน้าไปยังตำแหน่ง parent อื่น
• retrieve-a-database - รับ metadata ของฐานข้อมูลรวมถึง data source IDs

การเปลี่ยนแปลงพารามิเตอร์:

• การดำเนินการกับฐานข้อมูลทั้งหมดตอนนี้ใช้ data_source_id แทน database_id
• ค่าตัวกรองการค้นหาเปลี่ยนจาก ["page", "database"] เป็น ["page", "data_source"]
• การสร้างหน้าตอนนี้รองรับทั้ง page_id และ database_id parents (สำหรับ data sources)

ฉันจำเป็นต้องย้ายหรือไม่?

ไม่จำเป็นต้องเปลี่ยนแปลงโค้ด เครื่องมือ MCP จะถูกค้นพบโดยอัตโนมัติเมื่อเซิร์ฟเวอร์เริ่มทำงาน เมื่อคุณอัปเกรดเป็น v2.0.0 ไคลเอนต์ AI จะเห็นชื่อเครื่องมือและพารามิเตอร์ใหม่โดยอัตโนมัติ เครื่องมือฐานข้อมูลแบบเก่าจะไม่สามารถใช้งานได้อีกต่อไป

หากคุณมีชื่อเครื่องมือหรือ prompts ที่ hardcode ไว้ซึ่งอ้างอิงถึงเครื่องมือฐานข้อมูลแบบเก่า ให้อัปเดตเพื่อใช้เครื่องมือ data source ใหม่:

เครื่องมือเก่า (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 ยังคงใช้งานได้และส่งคืน metadata ของฐานข้อมูลรวมถึงรายการ data source IDs ใช้ retrieve-a-data-source เพื่อรับ schema และคุณสมบัติของ data source เฉพาะ

จำนวนเครื่องมือทั้งหมดตอนนี้: 22 รายการ (จากเดิม 19 รายการใน v1.x)

---

เนื้อหาหน้าในรูปแบบ Markdown

เซิร์ฟเวอร์มีเครื่องมือสองตัวสำหรับทำงานกับเนื้อหาหน้าในรูปแบบ enhanced Markdown แทนที่จะเป็น block JSON ซึ่งมีประสิทธิภาพด้าน token มากกว่าสำหรับ AI agents:

• retrieve-page-markdown — อ่านเนื้อหาทั้งหมดของหน้าในรูปแบบ Markdown (GET /v1/pages/{page_id}/markdown) ส่ง include_transcript: true เพื่อแทรก transcripts การประชุม
• update-page-markdown — แก้ไขเนื้อหาของหน้าด้วย Markdown (PATCH /v1/pages/{page_id}/markdown) แนะนำให้ใช้ replace_content เพื่อเขียนทับทั้งหน้า หรือ update_content สำหรับการแก้ไขแบบค้นหาและแทนที่เฉพาะจุด

endpoints เหล่านี้ต้องการ Notion API เวอร์ชัน 2026-03-11 ตอนนี้เซิร์ฟเวอร์ดึง header Notion-Version ต่อการดำเนินการ จาก OpenAPI spec ดังนั้นเครื่องมือเหล่านี้จึงใช้ 2026-03-11 ในขณะที่ API ส่วนที่เหลือยังคงใช้ 2025-09-03 — ไม่จำเป็นต้องกำหนดค่าใดๆ หากคุณตั้งค่า Notion-Version ด้วยตัวเองผ่าน OPENAPI_MCP_HEADERS ค่าของคุณจะถูกใช้ก่อนสำหรับทุกเครื่องมือ

---

การติดตั้ง

1. การตั้งค่า integration ใน Notion

ไปที่ https://www.notion.so/profile/integrations และสร้าง integration ภายใน ใหม่ หรือเลือกอันที่มีอยู่แล้ว

ในขณะที่เราจำกัดขอบเขตของ Notion API ที่เปิดเผย (ตัวอย่างเช่น คุณจะไม่สามารถลบฐานข้อมูลผ่าน MCP ได้) แต่ก็ยังมีความเสี่ยงที่ไม่เป็นศูนย์ต่อข้อมูล workspace เมื่อเปิดเผยต่อ LLMs ผู้ใช้ที่ใส่ใจด้านความปลอดภัยอาจต้องการกำหนดค่า Capabilities ของ Integration เพิ่มเติม

ตัวอย่างเช่น คุณสามารถสร้าง integration token แบบอ่านอย่างเดียวได้โดยให้สิทธิ์ "Read content" จากแท็บ "Configuration" เท่านั้น:

2. การเชื่อมต่อเนื้อหาเข้ากับ integration

ตรวจสอบให้แน่ใจว่าหน้าและฐานข้อมูลที่เกี่ยวข้องเชื่อมต่อกับ integration ของคุณ

ในการดำเนินการนี้ ให้ไปที่แท็บ Access ในการตั้งค่า integration ภายในของคุณ แก้ไขการเข้าถึงและเลือกหน้าที่คุณต้องการใช้

อีกทางหนึ่ง คุณสามารถให้สิทธิ์การเข้าถึงหน้าเป็นรายหน้าได้ คุณจะต้องไปที่หน้าเป้าหมาย คลิกที่จุด 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

มีสองตัวเลือกสำหรับการรันเซิร์ฟเวอร์ MCP ด้วย Docker:

ตัวเลือก 1: การใช้ Docker Hub image อย่างเป็นทางการ

เพิ่มสิ่งต่อไปนี้ลงใน .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 image อย่างเป็นทางการ
• จัดการการ escape JSON ผ่าน environment variables อย่างถูกต้อง
• ให้วิธีการกำหนดค่าที่น่าเชื่อถือมากขึ้น

ตัวเลือก 2: การสร้าง Docker image ในเครื่อง

คุณยังสามารถสร้างและรัน Docker image ในเครื่องได้อีกด้วย ขั้นแรก สร้าง Docker image:

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_**** ด้วย integration secret ของคุณ ค้นหาได้จากแท็บการกำหนดค่า integration ของคุณ:

ตัวเลือก Transport

Notion MCP Server รองรับสองโหมด transport:

STDIO transport (ค่าเริ่มต้น)

โหมด transport เริ่มต้นใช้ standard input/output สำหรับการสื่อสาร นี่คือ MCP transport มาตรฐานที่ใช้โดยไคลเอนต์ส่วนใหญ่เช่น Claude Desktop

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

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

Streamable HTTP transport

สำหรับแอปพลิเคชันบนเว็บหรือไคลเอนต์ที่ต้องการการสื่อสารผ่าน HTTP คุณสามารถใช้ Streamable HTTP transport ได้:

# 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 transport เซิร์ฟเวอร์จะพร้อมใช้งานที่ http://127.0.0.1:<port>/mcp ตามค่าเริ่มต้น

การตรวจสอบสิทธิ์

Streamable HTTP transport ต้องการการตรวจสอบสิทธิ์แบบ bearer token เพื่อความปลอดภัย คุณมีสามตัวเลือก:

ตัวเลือก 1: โทเค็นที่สร้างขึ้นอัตโนมัติ (สำหรับการพัฒนาเท่านั้น)

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

เซิร์ฟเวอร์จะสร้างโทเค็นแบบสุ่มที่ปลอดภัยและเขียนลงในไฟล์ที่มีการจำกัดสิทธิ์:

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

ตัวเลือก 2: โทเค็นที่กำหนดเองผ่าน command line (แนะนำสำหรับ production)

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

ตัวเลือก 3: โทเค็นที่กำหนดเองผ่าน environment variable (แนะนำสำหรับ production)

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

อาร์กิวเมนต์ command line --auth-token มีความสำคัญกว่า environment variable AUTH_TOKEN หากระบุทั้งสองอย่าง

ตัวเลือกที่ไม่ปลอดภัย: ปิดใช้งานการตรวจสอบสิทธิ์ HTTP

คุณสามารถปิดใช้งานการตรวจสอบสิทธิ์แบบ bearer token ได้ด้วยแฟล็ก unsafe ที่ชัดเจนเท่านั้น:

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

คำเตือน: --unsafe-disable-auth ไม่ปลอดภัย เซิร์ฟเวอร์อาจเข้าถึงได้จากหน้าที่คุณเยี่ยมชมผ่าน DNS rebinding ใช้เฉพาะบนเครือข่ายที่แยกส่วนเท่านั้น

เมื่อปิดใช้งานการตรวจสอบสิทธิ์ เซิร์ฟเวอร์จะเปิดใช้งานการป้องกัน DNS rebinding โดยการตรวจสอบ headers Host และ Origin กับ local host และ loopback hosts ที่กำหนดค่าไว้ แฟล็ก --disable-auth ก่อนหน้านี้ยังคงยอมรับเป็น alias ที่เลิกใช้แล้ว แต่จะพิมพ์คำเตือน

การส่งคำขอ HTTP

คำขอทั้งหมดไปยัง Streamable HTTP transport ต้องรวม bearer token ใน Authorization header:

# 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

หมายเหตุ: ตรวจสอบให้แน่ใจว่าได้ตั้งค่า environment variable NOTION_TOKEN (แนะนำ) หรือ environment variable OPENAPI_MCP_HEADERS ด้วยโทเค็น integration ของ Notion เมื่อใช้โหมด transport ใดๆ

การให้บริการหลาย integrations (การส่งผ่านโทเค็นต่อคำขอ)

ตามค่าเริ่มต้น เซิร์ฟเวอร์จะตรวจสอบสิทธิ์กับ Notion ด้วยโทเค็นเดียวที่ฝังไว้ตอนเริ่มต้น ซึ่งล็อกการ deploy หนึ่งครั้งกับหนึ่ง Notion integration เพื่อให้การ deploy ครั้งเดียวสามารถให้บริการ หลาย integrations ได้ ให้เปิดใช้งานการส่งผ่านโทเค็นเพื่อให้แต่ละไคลเอนต์ส่งโทเค็น integration ของ Notion ของตัวเองต่อการเชื่อมต่อ:

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

จากนั้นไคลเอนต์จะส่งโทเค็น Notion ของพวกเขาในคำขอ initialize โดยใช้ header 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

ลำดับการแก้ไขโทเค็นสำหรับแต่ละการเชื่อมต่อ:

1. header Notion-Token (แนะนำ — ไม่กำกวม และทำงานร่วมกับการตรวจสอบสิทธิ์เกตเวย์ Authorization ของเซิร์ฟเวอร์เอง) หากมีอยู่ จะต้องเป็นโทเค็น Notion ที่ถูกต้อง มิฉะนั้นคำขอจะถูกปฏิเสธด้วย 401
2. Authorization: Bearer ntn_**** — เฉพาะเมื่อปิดการตรวจสอบสิทธิ์ bearer ของเซิร์ฟเวอร์เอง (--unsafe-disable-auth) ดังนั้น header จึงว่างพอที่จะส่งโทเค็น Notion โดยตรง
3. มิฉะนั้น จะใช้โทเค็น env ตอนเริ่มต้น (NOTION_TOKEN / OPENAPI_MCP_HEADERS) หากตั้งค่าไว้ ดังนั้นการส่งผ่านโทเค็นและ integration เริ่มต้นสามารถอยู่ร่วมกันได้ในการ deploy ครั้งเดียว

หมายเหตุ:

• เฉพาะค่าที่มีคำนำหน้าโทเค็น Notion (ntn_, แบบเก่า secret_) เท่านั้นที่ถือว่าเป็นโทเค็น Notion ดังนั้น secret เกตเวย์ของเซิร์ฟเวอร์และโทเค็น Notion ของผู้เช่าจะไม่ชนกัน
• แต่ละโทเค็นผูกกับเซสชัน MCP ของมัน โทเค็นจะไม่ถูกบันทึก (เฉพาะคำนำหน้าที่ถูกปกปิดเท่านั้นที่ถูกปล่อยออกมา)
• นี่คือการตั้งค่าการส่งผ่านโทเค็นโดยเจตนา ควร deploy ผ่าน TLS เสมอ และแนะนำให้เปิดใช้งานการตรวจสอบสิทธิ์ bearer ของเซิร์ฟเวอร์เอง (--auth-token) เป็นเกตเวย์ด้านหน้าทราฟฟิกแบบ multi-tenant

ตัวอย่าง

1. การใช้คำสั่งต่อไปนี้

Comment "Hello MCP" on page "Getting started"

AI จะวางแผนการเรียก API สองครั้งคือ v1/search และ v1/comments อย่างถูกต้องเพื่อให้งานสำเร็จ

1. ในทำนองเดียวกัน คำสั่งต่อไปนี้จะส่งผลให้มีหน้าใหม่ชื่อ "Notion MCP" เพิ่มไปยังหน้า parent "Development"

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

1. คุณยังสามารถอ้างอิง content ID โดยตรงได้

Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

การพัฒนา

Build & test

npm run build
npm test

Execute

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

การทดสอบการเปลี่ยนแปลงในเครื่องด้วย Cursor:

1. รันคำสั่ง npm link จาก root ของ repository เพื่อสร้าง symlink ทั่วทั้งเครื่องไปยังแพ็คเกจ notion-mcp-server
2. รวม snippet การกำหนดค่าด้านล่างลงใน mcp.json ของ Cursor (หรือไคลเอนต์ MCP อื่นที่คุณต้องการทดสอบ)
3. (Cleanup) รัน npm unlink จาก root ของ repository

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

Publish

npm login
npm publish --access public