Notion MCP

Server MCP Notion

[!NOTE]

Kami telah memperkenalkan Notion MCP, server MCP jarak jauh dengan peningkatan berikut:

• Pemasangan mudah melalui OAuth standar. Tidak perlu lagi mengutak-atik JSON atau token API.
• Alat canggih yang disesuaikan untuk agen AI, termasuk mengedit halaman dalam Markdown. Alat ini dirancang dengan mempertimbangkan konsumsi token yang dioptimalkan.

Pelajari lebih lanjut dan mulai di dokumentasi Notion MCP.

Kami memprioritaskan, dan hanya menyediakan dukungan aktif untuk, Notion MCP (jarak jauh). Akibatnya:

• Kami mungkin menghentikan repositori server MCP lokal ini di masa mendatang.
• Isu dan pull request di sini tidak dipantau secara aktif.
• Harap jangan mengajukan isu terkait MCP jarak jauh di sini; sebagai gantinya, hubungi dukungan Notion.

Proyek ini mengimplementasikan server MCP untuk API Notion.

---

⚠️ Perubahan besar versi 2.0.0

Versi 2.0.0 bermigrasi ke API Notion 2025-09-03 yang memperkenalkan sumber data sebagai abstraksi utama untuk basis data.

Apa yang berubah

Alat yang dihapus (3):

• post-database-query - digantikan oleh query-data-source
• update-a-database - digantikan oleh update-a-data-source
• create-a-database - digantikan oleh create-a-data-source

Alat baru (7):

• query-data-source - Kueri sumber data (basis data) dengan filter dan pengurutan
• retrieve-a-data-source - Dapatkan metadata dan skema untuk sumber data
• update-a-data-source - Perbarui properti sumber data
• create-a-data-source - Buat sumber data baru
• list-data-source-templates - Daftar templat yang tersedia di sumber data
• move-page - Pindahkan halaman ke lokasi induk yang berbeda
• retrieve-a-database - Dapatkan metadata basis data termasuk ID sumber datanya

Perubahan parameter:

• Semua operasi basis data sekarang menggunakan data_source_id alih-alih database_id
• Nilai filter pencarian berubah dari ["page", "database"] menjadi ["page", "data_source"]
• Pembuatan halaman sekarang mendukung induk page_id dan database_id (untuk sumber data)

Apakah saya perlu bermigrasi?

Tidak diperlukan perubahan kode. Alat MCP ditemukan secara otomatis saat server dimulai. Saat Anda meningkatkan ke v2.0.0, klien AI akan secara otomatis melihat nama dan parameter alat baru. Alat basis data lama tidak lagi tersedia.

Jika Anda memiliki nama alat atau prompt yang dikodekan secara keras yang merujuk ke alat basis data lama, perbarui untuk menggunakan alat sumber data baru:

Alat Lama (v1.x)	Alat Baru (v2.0)	Perubahan Parameter
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	Tidak ada perubahan (menggunakan parent.page_id)

Catatan: retrieve-a-database masih tersedia dan mengembalikan metadata basis data termasuk daftar ID sumber data. Gunakan retrieve-a-data-source untuk mendapatkan skema dan properti dari sumber data tertentu.

Total alat sekarang: 22 (sebelumnya 19 di v1.x)

---

Konten halaman sebagai Markdown

Server menyediakan dua alat untuk bekerja dengan konten halaman sebagai Markdown yang ditingkatkan alih-alih JSON blok, yang secara signifikan lebih hemat token untuk agen AI:

• retrieve-page-markdown — Baca konten lengkap halaman sebagai Markdown (GET /v1/pages/{page_id}/markdown). Berikan include_transcript: true untuk menyisipkan transkrip catatan rapat.
• update-page-markdown — Edit konten halaman dengan Markdown (PATCH /v1/pages/{page_id}/markdown). Lebih suka replace_content untuk menimpa seluruh halaman, atau update_content untuk pengeditan temukan-dan-ganti yang ditargetkan.

Titik akhir ini memerlukan versi API Notion 2026-03-11. Server sekarang mengambil header Notion-Version per operasi dari spesifikasi OpenAPI, sehingga alat ini menggunakan 2026-03-11 sementara sisa API terus menggunakan 2025-09-03 — tidak perlu konfigurasi. Jika Anda mengatur Notion-Version sendiri melalui OPENAPI_MCP_HEADERS, nilai Anda akan diutamakan untuk setiap alat.

---

Pemasangan

1. Menyiapkan integrasi di Notion

Buka https://www.notion.so/profile/integrations dan buat integrasi internal baru atau pilih yang sudah ada.

Meskipun kami membatasi cakupan API Notion yang diekspos (misalnya, Anda tidak akan dapat menghapus basis data melalui MCP), ada risiko non-nol terhadap data ruang kerja dengan mengeksposnya ke LLM. Pengguna yang sadar keamanan mungkin ingin lebih mengonfigurasi Kemampuan Integrasi.

Misalnya, Anda dapat membuat token integrasi hanya-baca dengan hanya memberikan akses "Baca konten" dari tab "Konfigurasi":

2. Menghubungkan konten ke integrasi

Pastikan halaman dan basis data yang relevan terhubung ke integrasi Anda.

Untuk melakukannya, kunjungi tab Akses di pengaturan integrasi internal Anda. Edit akses dan pilih halaman yang ingin Anda gunakan.

Atau, Anda dapat memberikan akses halaman secara individual. Anda perlu mengunjungi halaman target, klik 3 titik, dan pilih "Hubungkan ke integrasi".

3. Menambahkan konfigurasi MCP ke klien Anda

Menggunakan npm

Cursor & Claude

Tambahkan berikut ini ke .cursor/mcp.json atau claude_desktop_config.json Anda (MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json)

Opsi 1: Menggunakan NOTION_TOKEN (disarankan)

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

Opsi 2: Menggunakan OPENAPI_MCP_HEADERS (untuk kasus penggunaan lanjutan)

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

Zed

Tambahkan berikut ini ke settings.json Anda

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

Gunakan Copilot CLI untuk menambahkan server MCP secara interaktif:

/mcp add

Atau, buat atau edit file konfigurasi ~/.copilot/mcp-config.json dan tambahkan:

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

Untuk informasi lebih lanjut, lihat dokumentasi Copilot CLI.

Menggunakan Docker

Ada dua opsi untuk menjalankan server MCP dengan Docker:

Opsi 1: Menggunakan image Docker Hub resmi

Tambahkan berikut ini ke .cursor/mcp.json atau claude_desktop_config.json Anda

Menggunakan NOTION_TOKEN (disarankan):

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

Menggunakan OPENAPI_MCP_HEADERS (untuk kasus penggunaan lanjutan):

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

Pendekatan ini:

• Menggunakan image Docker Hub resmi
• Menangani pelolosan JSON dengan benar melalui variabel lingkungan
• Menyediakan metode konfigurasi yang lebih andal

Opsi 2: Membangun image Docker secara lokal

Anda juga dapat membangun dan menjalankan image Docker secara lokal. Pertama, bangun image Docker:

docker compose build

Kemudian, tambahkan berikut ini ke .cursor/mcp.json atau claude_desktop_config.json Anda

Menggunakan NOTION_TOKEN (disarankan):

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

Menggunakan OPENAPI_MCP_HEADERS (untuk kasus penggunaan lanjutan):

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

Jangan lupa untuk mengganti ntn_**** dengan rahasia integrasi Anda. Temukan dari tab konfigurasi integrasi Anda:

Opsi transport

Server MCP Notion mendukung dua mode transport:

Transport STDIO (default)

Mode transport default menggunakan input/output standar untuk komunikasi. Ini adalah transport MCP standar yang digunakan oleh sebagian besar klien seperti Claude Desktop.

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

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

Transport HTTP Streamable

Untuk aplikasi berbasis web atau klien yang lebih suka komunikasi HTTP, Anda dapat menggunakan transport HTTP Streamable:

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

Saat menggunakan transport HTTP Streamable, server akan tersedia di http://127.0.0.1:<port>/mcp secara default.

Otentikasi

Transport HTTP Streamable memerlukan otentikasi token pembawa untuk keamanan. Anda memiliki tiga opsi:

Opsi 1: Token yang dihasilkan otomatis (hanya untuk pengembangan)

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

Server akan menghasilkan token acak yang aman dan menuliskannya ke file dengan izin terbatas:

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

Opsi 2: Token kustom melalui baris perintah (disarankan untuk produksi)

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

Opsi 3: Token kustom melalui variabel lingkungan (disarankan untuk produksi)

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

Argumen baris perintah --auth-token lebih diutamakan daripada variabel lingkungan AUTH_TOKEN jika keduanya disediakan.

Opsi tidak aman: nonaktifkan otentikasi HTTP

Anda dapat menonaktifkan otentikasi token pembawa hanya dengan flag tidak aman eksplisit:

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

PERINGATAN: --unsafe-disable-auth tidak aman. Server mungkin dapat dijangkau oleh halaman yang Anda kunjungi melalui DNS rebinding. Hanya gunakan di jaringan terisolasi.

Saat otentikasi dinonaktifkan, server mengaktifkan perlindungan DNS rebinding dengan memeriksa header Host dan Origin terhadap host lokal dan host loopback yang dikonfigurasi. Flag --disable-auth sebelumnya masih diterima sebagai alias usang, tetapi akan mencetak peringatan.

Membuat permintaan HTTP

Semua permintaan ke transport HTTP Streamable harus menyertakan token pembawa di 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

Catatan: Pastikan untuk mengatur variabel lingkungan NOTION_TOKEN (disarankan) atau variabel lingkungan OPENAPI_MCP_HEADERS dengan token integrasi Notion Anda saat menggunakan salah satu mode transport.

Melayani beberapa integrasi (penerusan token per-permintaan)

Secara default server mengotentikasi ke Notion dengan satu token yang disematkan saat startup, yang mengunci satu penyebaran ke satu integrasi Notion. Untuk memungkinkan satu penyebaran melayani beberapa integrasi, aktifkan penerusan token sehingga setiap klien menyediakan token integrasi Notion sendiri per koneksi:

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

Klien kemudian mengirim token Notion mereka pada permintaan initialize menggunakan header khusus 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

Bagaimana token diselesaikan untuk setiap koneksi, secara berurutan:

1. Header Notion-Token (lebih disukai — tidak ambigu, dan bekerja bersama otentikasi gateway Authorization server sendiri). Jika ada, harus berupa token Notion yang valid, jika tidak permintaan ditolak dengan 401.
2. Authorization: Bearer ntn_**** — hanya ketika otentikasi pembawa server sendiri dimatikan (--unsafe-disable-auth), sehingga header bebas membawa token Notion secara langsung.
3. Jika tidak, token env startup (NOTION_TOKEN / OPENAPI_MCP_HEADERS), jika diatur, sehingga penerusan dan integrasi default dapat hidup berdampingan dalam satu penyebaran.

Catatan:

• Hanya nilai dengan awalan token Notion (ntn_, legacy secret_) yang diperlakukan sebagai token Notion, sehingga rahasia gateway server dan token Notion penyewa tidak pernah bentrok.
• Setiap token terikat ke sesi MCP-nya; token tidak pernah dicatat (hanya awalan yang disunting yang dipancarkan).
• Ini adalah pengaturan penerusan token yang disengaja. Selalu sebarkan melalui TLS, dan lebih suka menjaga otentikasi pembawa server sendiri (--auth-token) tetap aktif sebagai gateway di depan lalu lintas multi-penyewa.

Contoh

1. Menggunakan instruksi berikut

Comment "Hello MCP" on page "Getting started"

AI akan merencanakan dua panggilan API dengan benar, v1/search dan v1/comments, untuk mencapai tugas

1. Demikian pula, instruksi berikut akan menghasilkan halaman baru bernama "Notion MCP" ditambahkan ke halaman induk "Development"

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

1. Anda juga dapat merujuk ID konten secara langsung

Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

Pengembangan

Bangun & uji

npm run build
npm test

Jalankan

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

Menguji perubahan secara lokal di Cursor:

1. Jalankan perintah npm link dari root repositori untuk membuat symlink global mesin ke paket notion-mcp-server.
2. Gabungkan cuplikan konfigurasi di bawah ini ke mcp.json Cursor (atau klien MCP lain yang ingin Anda uji).
3. (Pembersihan) jalankan npm unlink dari root repositori.

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

Publikasikan

npm login
npm publish --access public