Notion MCP

Notion MCP Sunucusu

[!NOTE]

Aşağıdaki iyileştirmeleri içeren Notion MCP adlı uzak bir MCP sunucusunu kullanıma sunduk:

• Standart OAuth ile kolay kurulum. Artık JSON veya API belirteçleriyle uğraşmanıza gerek yok.
• Sayfaları Markdown ile düzenleme dahil, yapay zeka aracılarına özel olarak tasarlanmış güçlü araçlar. Bu araçlar, optimize edilmiş belirteç tüketimi göz önünde bulundurularak tasarlanmıştır.

Daha fazla bilgi edinmek ve başlamak için Notion MCP belgelerine bakın.

Notion MCP (uzak) sunucusuna öncelik veriyor ve yalnızca onun için aktif destek sağlıyoruz. Bunun sonucu olarak:

• Gelecekte bu yerel MCP sunucu deposunu kullanımdan kaldırabiliriz.
• Buradaki sorunlar ve çekme istekleri aktif olarak izlenmemektedir.
• Lütfen uzak MCP ile ilgili sorunları buraya bildirmeyin; bunun yerine Notion desteğiyle iletişime geçin.

Bu proje, Notion API için bir MCP sunucusu uygular.

---

⚠️ Sürüm 2.0.0 kırılım değişiklikleri

Sürüm 2.0.0, veritabanları için birincil soyutlama olarak veri kaynaklarını tanıtan Notion API 2025-09-03'e geçiş yapar.

Neler değişti

Kaldırılan araçlar (3):

• post-database-query - query-data-source ile değiştirildi
• update-a-database - update-a-data-source ile değiştirildi
• create-a-database - create-a-data-source ile değiştirildi

Yeni araçlar (7):

• query-data-source - Bir veri kaynağını (veritabanı) filtreler ve sıralamalarla sorgula
• retrieve-a-data-source - Bir veri kaynağı için meta veri ve şema al
• update-a-data-source - Veri kaynağı özelliklerini güncelle
• create-a-data-source - Yeni bir veri kaynağı oluştur
• list-data-source-templates - Bir veri kaynağındaki mevcut şablonları listele
• move-page - Bir sayfayı farklı bir üst konuma taşı
• retrieve-a-database - Veri kaynağı kimlikleri dahil veritabanı meta verisini al

Parametre değişiklikleri:

• Tüm veritabanı işlemleri artık database_id yerine data_source_id kullanır
• Arama filtresi değerleri ["page", "database"] yerine ["page", "data_source"] olarak değişti
• Sayfa oluşturma artık (veri kaynakları için) hem page_id hem de database_id üst öğelerini destekler

Geçiş yapmam gerekiyor mu?

Kod değişikliği gerekmez. MCP araçları, sunucu başlatıldığında otomatik olarak keşfedilir. v2.0.0'a yükselttiğinizde, yapay zeka istemcileri yeni araç adlarını ve parametreleri otomatik olarak görecektir. Eski veritabanı araçları artık kullanılamaz.

Eski veritabanı araçlarına atıfta bulunan sabit kodlanmış araç adlarınız veya istemleriniz varsa, bunları yeni veri kaynağı araçlarını kullanacak şekilde güncelleyin:

Eski Araç (v1.x)	Yeni Araç (v2.0)	Parametre Değişikliği
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	Değişiklik yok (parent.page_id kullanır)

Not: retrieve-a-database hala kullanılabilir ve veri kaynağı kimliklerinin listesi dahil veritabanı meta verisini döndürür. Belirli bir veri kaynağının şemasını ve özelliklerini almak için retrieve-a-data-source kullanın.

Toplam araç sayısı şimdi: 22 (v1.x'te 19 idi)

---

Markdown olarak sayfa içeriği

Sunucu, blok JSON yerine gelişmiş Markdown olarak sayfa içeriğiyle çalışmak için iki araç sunar; bu, yapay zeka aracıları için belirteç açısından önemli ölçüde daha verimlidir:

• retrieve-page-markdown — Bir sayfanın tam içeriğini Markdown olarak oku (GET /v1/pages/{page_id}/markdown). Toplantı notu transkriptlerini satır içine almak için include_transcript: true iletin.
• update-page-markdown — Bir sayfanın içeriğini Markdown ile düzenle (PATCH /v1/pages/{page_id}/markdown). Tüm sayfanın üzerine yazmak için replace_content veya hedefli bul ve değiştir düzenlemeleri için update_content tercih edin.

Bu uç noktalar, Notion API sürümü 2026-03-11 gerektirir. Sunucu artık Notion-Version başlığını OpenAPI spesifikasyonundan işlem başına alır, böylece bu araçlar 2026-03-11 kullanırken API'nin geri kalanı 2025-09-03 kullanmaya devam eder — yapılandırma gerekmez. Notion-Version değerini OPENAPI_MCP_HEADERS aracılığıyla kendiniz ayarlarsanız, değeriniz her araç için öncelik kazanır.

---

Kurulum

1. Notion'da entegrasyonu ayarlama

https://www.notion.so/profile/integrations adresine gidin ve yeni bir dahili entegrasyon oluşturun veya mevcut birini seçin.

Notion API'nin kapsamını sınırlandırsak da (örneğin, MCP aracılığıyla veritabanlarını silemezsiniz), çalışma alanı verilerini LLM'lere maruz bırakmanın sıfır olmayan bir riski vardır. Güvenlik bilincine sahip kullanıcılar, Entegrasyonun Yeteneklerini daha da yapılandırmak isteyebilir.

Örneğin, "Yapılandırma" sekmesinden yalnızca "İçeriği oku" erişimi vererek salt okunur bir entegrasyon belirteci oluşturabilirsiniz:

2. İçeriği entegrasyona bağlama

İlgili sayfaların ve veritabanlarının entegrasyonunuza bağlı olduğundan emin olun.

Bunu yapmak için, dahili entegrasyon ayarlarınızdaki Erişim sekmesini ziyaret edin. Erişimi düzenleyin ve kullanmak istediğiniz sayfaları seçin.

Alternatif olarak, sayfa erişimini tek tek verebilirsiniz. Hedef sayfayı ziyaret etmeniz, 3 noktaya tıklamanız ve "Entegrasyona bağlan"ı seçmeniz gerekir.

3. İstemcinize MCP yapılandırmasını ekleme

npm kullanarak

Cursor ve Claude

.cursor/mcp.json veya claude_desktop_config.json dosyanıza aşağıdakini ekleyin (MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json)

Seçenek 1: NOTION_TOKEN kullanma (önerilir)

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

Seçenek 2: OPENAPI_MCP_HEADERS kullanma (gelişmiş kullanım durumları için)

{
  "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 dosyanıza aşağıdakini ekleyin

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

MCP sunucusunu etkileşimli olarak eklemek için Copilot CLI'yi kullanın:

/mcp add

Alternatif olarak, ~/.copilot/mcp-config.json yapılandırma dosyasını oluşturun veya düzenleyin ve şunu ekleyin:

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

Daha fazla bilgi için Copilot CLI belgelerine bakın.

Docker kullanarak

MCP sunucusunu Docker ile çalıştırmak için iki seçenek vardır:

Seçenek 1: Resmi Docker Hub imajını kullanma

.cursor/mcp.json veya claude_desktop_config.json dosyanıza aşağıdakini ekleyin

NOTION_TOKEN kullanma (önerilir):

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

OPENAPI_MCP_HEADERS kullanma (gelişmiş kullanım durumları için):

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

Bu yaklaşım:

• Resmi Docker Hub imajını kullanır
• Ortam değişkenleri aracılığıyla JSON kaçışını düzgün şekilde işler
• Daha güvenilir bir yapılandırma yöntemi sağlar

Seçenek 2: Docker imajını yerel olarak oluşturma

Docker imajını yerel olarak da oluşturup çalıştırabilirsiniz. İlk olarak Docker imajını oluşturun:

docker compose build

Ardından, .cursor/mcp.json veya claude_desktop_config.json dosyanıza aşağıdakini ekleyin

NOTION_TOKEN kullanma (önerilir):

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

OPENAPI_MCP_HEADERS kullanma (gelişmiş kullanım durumları için):

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

ntn_**** yerine entegrasyon gizli anahtarınızı koymayı unutmayın. Entegrasyon yapılandırma sekmenizden bulabilirsiniz:

Aktarım seçenekleri

Notion MCP Sunucusu iki aktarım modunu destekler:

STDIO aktarımı (varsayılan)

Varsayılan aktarım modu, iletişim için standart giriş/çıkış kullanır. Bu, Claude Desktop gibi çoğu istemci tarafından kullanılan standart MCP aktarımıdır.

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

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

Akışkan HTTP aktarımı

Web tabanlı uygulamalar veya HTTP iletişimini tercih eden istemciler için Akışkan HTTP aktarımını kullanabilirsiniz:

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

Akışkan HTTP aktarımı kullanırken, sunucu varsayılan olarak http://127.0.0.1:<port>/mcp adresinde mevcut olacaktır.

Kimlik doğrulama

Akışkan HTTP aktarımı, güvenlik için taşıyıcı belirteç kimlik doğrulaması gerektirir. Üç seçeneğiniz vardır:

Seçenek 1: Otomatik oluşturulan belirteç (yalnızca geliştirme için)

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

Sunucu, güvenli bir rastgele belirteç oluşturacak ve bunu kısıtlı izinlere sahip bir dosyaya yazacaktır:

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

Seçenek 2: Komut satırı aracılığıyla özel belirteç (üretim için önerilir)

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

Seçenek 3: Ortam değişkeni aracılığıyla özel belirteç (üretim için önerilir)

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

Her ikisi de sağlanırsa, --auth-token komut satırı argümanı AUTH_TOKEN ortam değişkenine göre öncelik kazanır.

Güvensiz seçenek: HTTP kimlik doğrulamasını devre dışı bırakma

Taşıyıcı belirteç kimlik doğrulamasını yalnızca açık güvensiz bayrağı ile devre dışı bırakabilirsiniz:

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

UYARI: --unsafe-disable-auth güvensizdir. Sunucu, DNS yeniden bağlama yoluyla ziyaret ettiğiniz sayfalara erişilebilir olabilir. Yalnızca yalıtılmış bir ağda kullanın.

Kimlik doğrulama devre dışı bırakıldığında, sunucu Host ve Origin başlıklarını yapılandırılmış yerel ana bilgisayar ve geri döngü ana bilgisayarlarına karşı kontrol ederek DNS yeniden bağlama korumasını etkinleştirir. Önceki --disable-auth bayrağı hala kullanımdan kaldırılmış bir takma ad olarak kabul edilir, ancak bir uyarı yazdıracaktır.

HTTP istekleri yapma

Akışkan HTTP aktarımına yapılan tüm istekler, Yetkilendirme başlığında taşıyıcı belirteci içermelidir:

# 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

Not: Her iki aktarım modunu kullanırken de NOTION_TOKEN ortam değişkenini (önerilir) veya OPENAPI_MCP_HEADERS ortam değişkenini Notion entegrasyon belirtecinizle ayarladığınızdan emin olun.

Birden çok entegrasyona hizmet verme (istek başına belirteç geçişi)

Varsayılan olarak sunucu, başlangıçta yerleşik tek bir belirteçle Notion'a kimlik doğrular, bu da bir dağıtımı bir Notion entegrasyonuna kilitler. Tek bir dağıtımın birden çok entegrasyona hizmet vermesine izin vermek için, her istemcinin bağlantı başına kendi Notion entegrasyon belirtecini sağlaması için belirteç geçişini etkinleştirin:

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

İstemciler daha sonra initialize isteğinde özel Notion-Token başlığını kullanarak Notion belirteçlerini gönderir:

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

Her bağlantı için belirtecin çözülme sırası:

1. Notion-Token başlığı (tercih edilir — nettir ve sunucunun kendi Authorization ağ geçidi kimlik doğrulamasıyla birlikte çalışır). Varsa, geçerli bir Notion belirteci olmalıdır, aksi takdirde istek 401 ile reddedilir.
2. Authorization: Bearer ntn_**** — yalnızca sunucunun kendi taşıyıcı kimlik doğrulaması kapatıldığında (--unsafe-disable-auth), böylece başlık doğrudan Notion belirtecini taşımak için serbest olur.
3. Aksi takdirde, başlangıç ortam belirteci (NOTION_TOKEN / OPENAPI_MCP_HEADERS), ayarlanmışsa, böylece geçiş ve varsayılan bir entegrasyon tek bir dağıtımda bir arada bulunabilir.

Notlar:

• Yalnızca Notion belirteci ön ekine (ntn_, eski secret_) sahip değerler Notion belirteci olarak kabul edilir, böylece sunucunun ağ geçidi sırrı ile bir kiracının Notion belirteci asla çakışmaz.
• Her belirteç MCP oturumuna bağlıdır; belirteçler asla günlüğe kaydedilmez (yalnızca sansürlenmiş bir ön ek yayınlanır).
• Bu kasıtlı bir belirteç geçişi kurulumudur. Her zaman TLS üzerinden dağıtın ve çok kiracılı trafiğin önünde bir ağ geçidi olarak sunucunun kendi taşıyıcı kimlik doğrulamasını (--auth-token) etkin tutmayı tercih edin.

Örnekler

1. Aşağıdaki talimatı kullanarak

Comment "Hello MCP" on page "Getting started"

Yapay zeka, görevi gerçekleştirmek için v1/search ve v1/comments olmak üzere iki API çağrısını doğru şekilde planlayacaktır

1. Benzer şekilde, aşağıdaki talimat "Geliştirme" üst sayfasına eklenen "Notion MCP" adlı yeni bir sayfayla sonuçlanacaktır

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

1. İçerik kimliğine doğrudan da başvurabilirsiniz

Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

Geliştirme

Derleme ve test

npm run build
npm test

Çalıştırma

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

Değişiklikleri Cursor'da yerel olarak test etme:

1. notion-mcp-server paketine makine genelinde bir sembolik bağlantı oluşturmak için depo kökünden npm link komutunu çalıştırın.
2. Aşağıdaki yapılandırma parçacığını Cursor'un mcp.json dosyasına (veya test etmek istediğiniz diğer MCP istemcisine) birleştirin.
3. (Temizlik) depo kökünden npm unlink komutunu çalıştırın.

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

Yayımlama

npm login
npm publish --access public