Notion MCP

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

Server Notion MCP

[!NOTE]

Untuk pengalaman terbaik, gunakan Remote Notion MCP, server MCP hosted resmi kami. Repositori ini adalah implementasi server MCP self-hosted terpisah yang tidak lagi dikelola atau didukung secara aktif. Silakan gunakan Remote Notion MCP sebagai gantinya. Server ini dirancang khusus untuk memberikan hasil yang lebih cepat dengan menggunakan token yang jauh lebih sedikit kepada agen AI.

Remote Notion MCP dapat mencari ruang kerja dan aplikasi yang terhubung secara semantik, membaca dan mengedit halaman dalam Markdown, serta mengembalikan hanya konteks yang paling relevan. Artinya, lebih sedikit waktu menunggu, lebih sedikit penggunaan context-window, dan biaya token yang lebih rendah. Server ini juga menggunakan OAuth dan secara otomatis menghormati izin Notion yang sudah ada dari setiap pengguna—tanpa token API, konfigurasi JSON, berbagi halaman manual, atau server lokal yang harus dikelola.

Fitur	Remote Notion MCP	Proyek ini (lokal)
Pengalaman hosted yang cepat	✅	Berjalan dan diperbarui secara lokal
Respons yang hemat token	✅	Terbatas
Alat canggih yang disesuaikan untuk agen AI	✅	Alat dasar turunan API
Pencarian semantik di seluruh ruang kerja Notion Anda	✅	Hanya pencarian kata kunci
Pencarian AI Connector di aplikasi yang terhubung	✅	Tidak tersedia
Pembacaan dan pengeditan halaman berbasis Markdown	✅	Terbatas pada dua alat konten halaman
Pengaturan OAuth yang mulus	✅	Konfigurasi token dan JSON manual
Menghormati izin Notion yang sudah ada dari setiap pengguna	✅	Izin integrasi manual dan berbagi halaman
Dukungan aktif dan peningkatan berkelanjutan	✅	Tidak didukung secara aktif

Pelajari lebih lanjut dan mulai menggunakan dokumentasi Remote Notion MCP.

Kami memprioritaskan, dan hanya memberikan dukungan aktif untuk, Remote Notion MCP. Sebagai akibatnya:

• Kami dapat menghentikan repositori server MCP lokal ini di masa mendatang.
• Masalah dan pull request di sini tidak dipantau secara aktif.
• Mohon jangan mengajukan masalah yang terkait dengan MCP jarak jauh di sini; hubungi dukungan Notion sebagai gantinya.

Proyek ini mengimplementasikan server MCP untuk Notion API.

---

⚠️ Perubahan besar Versi 2.0.0

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

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 data source (database) dengan filter dan pengurutan
• retrieve-a-data-source - Dapatkan metadata dan skema untuk data source
• update-a-data-source - Perbarui properti data source
• create-a-data-source - Buat data source baru
• list-data-source-templates - Daftarkan template yang tersedia dalam data source
• move-page - Pindahkan halaman ke lokasi induk yang berbeda
• retrieve-a-database - Dapatkan metadata database termasuk ID data source-nya

Perubahan parameter:

• Semua operasi database 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 data source)

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 otomatis melihat nama alat dan parameter baru. Alat database lama tidak lagi tersedia.

Jika Anda memiliki nama alat atau prompt yang di-hardcode yang merujuk ke alat database lama, perbarui untuk menggunakan alat data source 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 database termasuk daftar ID data source. Gunakan retrieve-a-data-source untuk mendapatkan skema dan properti dari data source tertentu.

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

---

Konten halaman sebagai Markdown

Server ini menyediakan dua alat untuk bekerja dengan konten halaman sebagai Markdown yang disempurnakan 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). Gunakan replace_content untuk menimpa seluruh halaman, atau update_content untuk pengeditan temukan-dan-ganti yang ditargetkan.

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

---

Instalasi

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 Notion API yang diekspos (misalnya, Anda tidak akan dapat menghapus database melalui MCP), ada risiko non-nol terhadap data ruang kerja dengan mengeksposnya ke LLM. Pengguna yang sadar keamanan mungkin ingin mengonfigurasi lebih lanjut Capabilities Integrasi.

Misalnya, Anda dapat membuat token integrasi hanya-baca dengan memberikan hanya akses "Read content" dari tab "Configuration":

2. Menghubungkan konten ke integrasi

Pastikan halaman dan database yang relevan terhubung ke integrasi Anda.

Untuk melakukannya, kunjungi tab Access 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 "Connect to integration".

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 escaping 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 secret integrasi Anda. Temukan dari tab konfigurasi integrasi Anda:

Opsi transport

Server Notion MCP 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 menyukai 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.

Autentikasi

Transport HTTP Streamable memerlukan autentikasi token bearer untuk keamanan. Anda memiliki tiga opsi:

Opsi 1: Token yang dibuat 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 diberikan.

Opsi tidak aman: menonaktifkan autentikasi HTTP

Anda dapat menonaktifkan autentikasi token bearer hanya dengan flag unsafe yang eksplisit:

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

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

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

Membuat permintaan HTTP

Semua permintaan ke transport HTTP Streamable harus menyertakan token bearer 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 (passthrough token per-permintaan)

Secara default, server mengautentikasi ke Notion dengan satu token yang disematkan saat startup, yang mengunci satu deployment ke satu integrasi Notion. Untuk memungkinkan satu deployment melayani beberapa integrasi, aktifkan passthrough token sehingga setiap klien menyediakan token integrasi Notion-nya 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 berfungsi bersama autentikasi gateway Authorization server itu sendiri). Jika ada, harus berupa token Notion yang valid, jika tidak, permintaan ditolak dengan 401.
2. Authorization: Bearer ntn_**** — hanya jika autentikasi bearer server itu 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 passthrough dan integrasi default dapat hidup berdampingan pada satu deployment.

Catatan:

• Hanya nilai dengan prefiks token Notion (ntn_, legacy secret_) yang diperlakukan sebagai token Notion, sehingga secret gateway server dan token Notion penyewa tidak akan pernah bertabrakan.
• Setiap token terikat ke sesi MCP-nya; token tidak pernah dicatat (hanya prefiks yang disunting yang dikeluarkan).
• Ini adalah pengaturan passthrough token yang disengaja. Selalu gunakan melalui TLS, dan lebih suka menjaga autentikasi bearer server itu sendiri (--auth-token) tetap aktif sebagai gateway di depan lalu lintas multi-tenant.

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 tersebut

1. Demikian pula, instruksi berikut akan menghasilkan halaman baru bernama "Notion MCP" yang 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

Build & test

npm run build
npm test

Eksekusi

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 dalam 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_..."
      }
    }
  }
}

Publikasi

npm login
npm publish --access public