Notion MCP

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

Notion MCP Sunucusu

[!NOTE]

En iyi deneyim için Remote Notion MCP kullanın; bu, resmi olarak barındırılan MCP sunucumuzdur. Bu depo, artık aktif olarak bakımı yapılmayan veya desteklenmeyen ayrı, kendi kendine barındırılan bir MCP sunucu uygulamasıdır. Lütfen bunun yerine Remote Notion MCP kullanın. Yapay zeka ajanlarına çok daha az token kullanarak daha hızlı sonuçlar vermek üzere özel olarak tasarlanmıştır.

Remote Notion MCP, çalışma alanınızda ve bağlı uygulamalarda anlamsal olarak arama yapabilir, sayfaları Markdown olarak okuyup düzenleyebilir ve yalnızca en alakalı bağlamı döndürebilir. Bu, daha az bekleme süresi, daha az bağlam penceresi kullanımı ve daha düşük token maliyeti anlamına gelir. Ayrıca OAuth kullanır ve her kullanıcının mevcut Notion izinlerine otomatik olarak saygı gösterir—API token'ları, JSON yapılandırması, manuel sayfa paylaşımı veya bakımı yapılacak yerel bir sunucu olmadan.

Özellik	Remote Notion MCP	Bu proje (yerel)
Hızlı, barındırılan deneyim	✅	Yerel olarak çalışır ve güncellenir
Token açısından verimli yanıtlar	✅	Sınırlı
Yapay zeka ajanları için özel olarak tasarlanmış güçlü araçlar	✅	Temel API kaynaklı araçlar
Notion çalışma alanınızda anlamsal arama	✅	Yalnızca anahtar kelime araması
Bağlı uygulamalarda AI Bağlayıcı araması	✅	Kullanılamaz
Markdown yerel sayfa okuma ve düzenleme	✅	İki sayfa içeriği aracıyla sınırlı
Sorunsuz OAuth kurulumu	✅	Manuel token ve JSON yapılandırması
Her kullanıcının mevcut Notion izinlerine saygı gösterir	✅	Manuel entegrasyon izinleri ve sayfa paylaşımı
Aktif destek ve sürekli iyileştirmeler	✅	Aktif olarak desteklenmiyor

Daha fazla bilgi edinin ve Remote Notion MCP dokümantasyonu ile başlayın.

Remote Notion MCP'ye öncelik veriyoruz ve yalnızca onun için aktif destek sağlıyoruz. Sonuç olarak:

• Bu yerel MCP sunucu deposunu gelecekte 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'da uyumsuzluk yaratan değişiklikler

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

Neler değişti

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

• post-database-query - yerini query-data-source aldı
• update-a-database - yerini update-a-data-source aldı
• create-a-database - yerini create-a-data-source aldı

Yeni araçlar (7):

• query-data-source - Filtreler ve sıralamalarla bir veri kaynağını (veritabanını) sorgulayın
• retrieve-a-data-source - Bir veri kaynağının meta verilerini ve şemasını alın
• update-a-data-source - Veri kaynağı özelliklerini güncelleyin
• create-a-data-source - Yeni bir veri kaynağı oluşturun
• list-data-source-templates - Bir veri kaynağındaki mevcut şablonları listeleyin
• move-page - Bir sayfayı farklı bir üst konuma taşıyın
• retrieve-a-database - Veri kaynağı kimlikleri dahil veritabanı meta verilerini alın

Parametre değişiklikleri:

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

Geçiş yapmam gerekiyor mu?

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

Eski veritabanı araçlarına başvuran 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 hâlâ kullanılabilir ve veri kaynağı kimliklerinin listesi dahil veritabanı meta verilerini 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ı artık: 22 (v1.x'te 19'du)

---

Sayfa içeriği Markdown olarak

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

• retrieve-page-markdown — Bir sayfanın tüm içeriğini Markdown olarak okuyun (GET /v1/pages/{page_id}/markdown). Toplantı notu transkriptlerini satır içine almak için include_transcript: true değerini iletin.
• update-page-markdown — Bir sayfanın içeriğini Markdown ile düzenleyin (PATCH /v1/pages/{page_id}/markdown). Sayfanın tamamını üzerine yazmak için replace_content kullanmayı veya hedefli bul-ve-değiştir düzenlemeleri için update_content kullanmayı 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'sinin kapsamını sınırlandırsak da (örneğin, MCP üzerinden veritabanlarını silemeyeceksiniz), ç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 "Okuma içeriği" erişimi vererek salt okunur bir entegrasyon token'ı 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ızda Erişim sekmesini ziyaret edin. Erişimi düzenleyin ve kullanmak istediğiniz sayfaları seçin.

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

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

npm kullanarak

Cursor ve Claude

Aşağıdakileri .cursor/mcp.json veya claude_desktop_config.json dosyanıza 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 (ileri düzey 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

Aşağıdakileri settings.json dosyanıza 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'yı 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 dokümantasyonuna bakın.

Docker kullanarak

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

Seçenek 1: Resmi Docker Hub görüntüsünü kullanma

Aşağıdakileri .cursor/mcp.json veya claude_desktop_config.json dosyanıza 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 (ileri düzey 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 görüntüsünü kullanır
• Ortam değişkenleri aracılığıyla JSON kaçışını doğru şekilde işler
• Daha güvenilir bir yapılandırma yöntemi sağlar

Seçenek 2: Docker görüntüsünü yerel olarak oluşturma

Docker görüntüsünü yerel olarak da oluşturup çalıştırabilirsiniz. Önce Docker görüntüsünü oluşturun:

docker compose build

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

NOTION_TOKEN kullanma (önerilir):

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

OPENAPI_MCP_HEADERS kullanma (ileri düzey 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_**** değerini entegrasyon sırrınızla değiştirmeyi unutmayın. Entegrasyon yapılandırma sekmesinden bulabilirsiniz:

Taşıma (Transport) seçenekleri

Notion MCP Sunucusu iki taşıma modunu destekler:

STDIO taşıması (varsayılan)

Varsayılan taşıma modu, iletişim için standart girdi/çıktı kullanır. Bu, Claude Desktop gibi çoğu istemci tarafından kullanılan standart MCP taşıması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 taşıması

HTTP iletişimini tercih eden web tabanlı uygulamalar veya istemciler için Akışkan HTTP taşıması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 taşımasını kullanırken sunucu varsayılan olarak http://127.0.0.1:<port>/mcp adresinde kullanılabilir olacaktır.

Kimlik doğrulama

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

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

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

Sunucu güvenli bir rastgele token oluşturacak ve 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 token (ü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 token (üretim için önerilir)

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

Komut satırı bağımsız değişkeni --auth-token, her ikisi de sağlanırsa AUTH_TOKEN ortam değişkenine göre öncelik kazanır.

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

Taşıyıcı token kimlik doğrulamasını yalnızca açık güvenli olmayan bayrakla devre dışı bırakabilirsiniz:

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

UYARI: --unsafe-disable-auth güvenli değildir. Sunucu, DNS yeniden bağlama yoluyla ziyaret ettiğiniz sayfalara erişilebilir olabilir. Yalnızca izole 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 bilgisayara ve geri döngü ana bilgisayarlarına karşı kontrol ederek DNS yeniden bağlama korumasını etkinleştirir. Önceki --disable-auth bayrağı hâlâ kullanımdan kaldırılmış bir takma ad olarak kabul edilir, ancak bir uyarı yazdırır.

HTTP istekleri yapma

Akışkan HTTP taşımasına yapılan tüm istekler, Authorization başlığında taşıyıcı token'ı 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 taşıma modunu kullanırken NOTION_TOKEN ortam değişkenini (önerilir) veya OPENAPI_MCP_HEADERS ortam değişkenini Notion entegrasyon token'ınızla ayarladığınızdan emin olun.

Birden çok entegrasyona hizmet etme (istek başına token geçişi)

Varsayılan olarak sunucu, Notion'a başlangıçta gömülü tek bir token ile kimlik doğrular; bu da bir dağıtımı tek bir Notion entegrasyonuna kilitler. Tek bir dağıtımın birden çok entegrasyona hizmet etmesine izin vermek için, her istemcinin kendi Notion entegrasyon token'ını bağlantı başına sağlaması için token 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 Notion token'larını initialize isteğinde özel Notion-Token başlığını kullanarak 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 token'ın nasıl çözümlendiği, sırasıyla:

1. Notion-Token başlığı (tercih edilen—belirsiz değildir ve sunucunun kendi Authorization ağ geçidi kimlik doğrulamasıyla birlikte çalışır). Varsa geçerli bir Notion token'ı 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 Notion token'ını doğrudan taşımakta serbest kalır.
3. Aksi takdirde, ayarlanmışsa başlangıç ortam token'ı (NOTION_TOKEN / OPENAPI_MCP_HEADERS), böylece geçiş ve varsayılan bir entegrasyon tek bir dağıtımda bir arada bulunabilir.

Notlar:

• Yalnızca Notion token önekine (ntn_, eski secret_) sahip değerler Notion token'ları olarak kabul edilir; böylece sunucunun ağ geçidi sırrı ile bir kiracının Notion token'ı asla çakışmaz.
• Her token, kendi MCP oturumuna bağlıdır; token'lar asla günlüğe kaydedilmez (yalnızca gizlenmiş bir önek yayınlanır).
• Bu kasıtlı bir token geç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ı kullanma

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, "Development" üst sayfasına eklenen "Notion MCP" adında yeni bir sayfayla sonuçlanacaktır

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

1. Ayrıca iç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. Depo kök dizininden npm link komutunu çalıştırarak notion-mcp-server paketine makine genelinde bir sembolik bağlantı oluşturun.
2. Aşağıdaki yapılandırma parçasını Cursor'un mcp.json dosyasına (veya test etmek istediğiniz başka bir MCP istemcisine) ekleyin.
3. (Temizlik) Depo kök dizininden npm unlink komutunu çalıştırın.

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

Yayınlama

npm login
npm publish --access public