Neon MCP Server

Neon MCP Server, Neon Postgres veritabanlarınız ile doğal dil kullanarak etkileşime girmenize olanak tanıyan açık kaynaklı bir araçtır.

Model Context Protocol (MCP), büyük dil modelleri (LLM'ler) ile harici sistemler arasında bağlamı yönetmek için tasarlanmış standartlaştırılmış bir protokoldür. Bu depo, Neon için uzak bir MCP Server sağlar.

Neon'un MCP server'ı, doğal dil istekleri ile Neon API arasında bir köprü görevi görmektedir. MCP'yi temel alarak, isteklerinizi gerekli API çağrılarına çevirerek proje ve branch oluşturma, sorgu çalıştırma ve veritabanı göçlerini sorunsuzca gerçekleştirme gibi görevleri yönetmenizi sağlar.

Neon MCP server'ının temel özellikleri arasında:

• Doğal dil etkileşimi: Sezgisel, konuşumsal komutlar kullanarak Neon veritabanlarını yönetin.
• Basitleştirilmiş veritabanı yönetimi: SQL yazıp veya doğrudan Neon API'yi kullanmadan karmaşık işlemleri gerçekleştirin.
• Geliştirici olmayan kullanıcılar için erişilebilirlik: Değişken teknik geçmiş olan kullanıcıları Neon veritabanlarıyla etkileşim kurabilmeleri için güçlendirin.
• Veritabanı göçü desteği: Doğal dil aracılığıyla başlatılan veritabanı şeması değişiklikleri için Neon'un branch özelliklerinden yararlanın.

Örneğin, Claude Code veya herhangi bir MCP Client'ında, Neon ile aşağıdakiler gibi işlemleri gerçekleştirmek için doğal dil kullanabilirsiniz:

• Yeni bir Postgres veritabanı oluşturalım ve "my-database" olarak adlandıralım. Ardından, şu sütunları içeren "users" adında bir tablo oluşturalım: id, name, email ve password.
• "my-project" adlı projemde, users tablosuna "created_at" adlı yeni bir sütun ekleyen bir migration çalıştırmak istiyorum.
• Bütün Neon projelerim ve her birinde ne tür veri bulunduğu hakkında bir özet verebilir misin?

[!WARNING]
Neon MCP Server Güvenlik Değerlendirmeleri
Neon MCP Server, doğal dil istekleri aracılığıyla güçlü veritabanı yönetimi yeteneklerini sağlar. Yürütülmeden önce LLM tarafından istenen eylemleri her zaman gözden geçirin ve yetkilendirin. Yalnızca yetkili kullanıcılar ve uygulamaların Neon MCP Server'a erişim sahibi olduğundan emin olun.

Neon MCP Server, yalnızca yerel geliştirme ve IDE entegrasyonları için tasarlanmıştır. Neon MCP Server'ı üretim ortamlarında kullanmanızı önermiyoruz. Kaza veya yetkisiz değişikliklere neden olabilecek güçlü işlemler yürütebilir.

Daha fazla bilgi için bkz. MCP güvenlik rehberi →.

Neon MCP Server'ı Kurma

Neon MCP Server'ı kurmanız için birkaç seçeneğiniz vardır:

1. API Anahtarı ile Hızlı Kurulum (Cursor, VS Code ve Claude Code): Neon'un MCP Server'ını, agent skills ve VS Code uzantısını tek komutla otomatik olarak yapılandırmak için neonctl@latest init komutunu çalıştırın.
2. Uzak MCP Server (OAuth Tabanlı Kimlik Doğrulama): OAuth kullanarak kimlik doğrulamasıyla Neon'un yönetilen MCP server'ına bağlanın. Bu yöntem, API anahtarları yönetme ihtiyacını ortadan kaldırdığından daha kullanışlıdır. Ayrıca, yeni özellikler ve geliştirmeler yayınlandığı anda otomatik olarak alırsınız.
3. Uzak MCP Server (API Anahtarı Tabanlı Kimlik Doğrulama): API anahtarı kullanarak kimlik doğrulamasıyla Neon'un yönetilen MCP server'ına bağlanın. Bu yöntem, OAuth'un kullanılamadığı bir uzak agent'ı Neon'a bağlamak istediğinizde kullanışlıdır. Ayrıca, yeni özellikler ve geliştirmeler yayınlandığı anda otomatik olarak alırsınız.

Ön Koşullar

• Bir MCP Client uygulaması.
• Bir Neon hesabı.
• Node.js (>= v18.0.0): nodejs.org adresinden indirin.

Geliştirme için, Node.js 22+ gereklidir (pnpm Corepack aracılığıyla sağlanır — etkinleştirmek için corepack enable komutunu çalıştırın).

Seçenek 1. API Anahtarı ile Hızlı Kurulum

Bir API anahtarını manuel olarak oluşturmak istemiyorsunuz?

Neon'un MCP Server'ını tek komutla otomatik olarak yapılandırmak için neonctl@latest init komutunu çalıştırın:

npx neonctl@latest init

Bu, Cursor, VS Code (GitHub Copilot) ve Claude Code ile çalışır. OAuth aracılığıyla kimlik doğrulama yapacak, sizin için bir Neon API anahtarı oluşturacak ve editörünüzü otomatik olarak yapılandıracaktır.

Seçenek 2. Uzak Barındırılan MCP Server (OAuth Tabanlı Kimlik Doğrulama)

OAuth kullanarak kimlik doğrulamasıyla Neon'un yönetilen MCP server'ına bağlanın. Bu, en kolay kurulum yöntemidir, bu server'ın yerel kurulumunu gerektirmez ve client'ta yapılandırılan bir Neon API anahtarına gerek duyulmaz.

Çalışma alanınızdaki tüm algılanan agent'lar ve editörler için Neon MCP Server'ını eklemek üzere aşağıdaki komutu çalıştırın:

npx add-mcp https://mcp.neon.tech/mcp

Neon MCP Server'ını proje kapsamında yerine global MCP server listesine eklemek için -g bayrağını ekleyin.

Alternatif olarak, client'ınızın MCP server yapılandırma dosyasına (örneğin, mcp.json, mcp_config.json) aşağıdaki "Neon" girişini ekleyebilirsiniz:

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp"
    }
  }
}

Kiro: Kiro MCP config dosyanıza (~/.kiro/settings/mcp.json global için veya .kiro/settings/mcp.json proje kapsamında) aşağıdakini ekleyin:

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp"
    }
  }
}

Veya bu README'nin başındaki tek tıklamalı yükleme düğmesini kullanın. Daha fazla bilgi için Kiro MCP belgesine bakın.

• MCP client'ınızı yeniden başlatın veya yenileyin.
• Tarayıcınızda bir OAuth penceresi açılacaktır. MCP client'ınızın Neon hesabınıza erişim yetkisini vermek için istemler takip edin.

OAuth tabanlı kimlik doğrulama ile MCP server, varsayılan olarak kişisel Neon hesabınızın altındaki projeler üzerinde çalışır. Kuruluşa ait projelere erişmek veya bunları yönetmek için, MCP client'a isteminde org_id veya project_id açıkça sağlamanız gerekir.

Seçenek 3. Uzak Barındırılan MCP Server (API Anahtarı Tabanlı Kimlik Doğrulama)

Uzak MCP Server, client'ınız destekliyorsa Authorization başlığında bir API anahtarı kullanarak kimlik doğrulamayı da destekler.

Neon Console'de bir Neon API anahtarı oluşturun. Ardından, çalışma alanınızdaki tüm algılanan agent'lar ve editörler için Neon MCP Server'ını eklemek üzere aşağıdaki komutu çalıştırın:

npx add-mcp https://mcp.neon.tech/mcp --header "Authorization: Bearer <$NEON_API_KEY>"

Alternatif olarak, client'ınızın MCP server yapılandırma dosyasına (örneğin, mcp.json, mcp_config.json) aşağıdaki "Neon" girişini ekleyebilirsiniz:

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp",
      "headers": {
        "Authorization": "Bearer <$NEON_API_KEY>"
      }
    }
  }
}

Kuruluşun API anahtarını sağlayarak erişimi yalnızca o kuruluş altındaki projelerle sınırlayın.

Kapsamlar ve Salt Okunur Mod

Neon MCP, OAuth kapsamlarını read, write ve * (* her ikisini de anlamına gelir) destekler. MCP client'ınız bu kapsamları doğrudan isteyebilir veya OAuth izinleri UI'sinde seçim yapabilirsiniz.

Salt okunur mod, projeleri oluşturma, branch'ler oluşturma veya migration'ları çalıştırma gibi yazma işlemlerini devre dışı bırakarak hangi araçların kullanılabileceğini kısıtlar. Salt okunur araçlar, projeleri listeleme, şemaları açıklama, veri sorgulama ve performans metriklerini görüntülemeyi içerir.

Salt okunur modu iki şekilde ayarlayabilirsiniz:

1. OAuth scope seçimi (önerilen): OAuth'ta, yetkilendirme UI'sinde Tam erişim seçeneğini işaretini kaldırarak salt okunur seçin.
2. readonly sorgu parametresi: MCP server URL'sine ?readonly=true ekleyin:

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?readonly=true"
    }
  }
}

Sorgu parametresi nasıl davranır:

• API anahtarı akışı: readonly=true salt okunur modu etkinleştirmenin yoludur (bu akışta OAuth scope değişimi yoktur).
• OAuth akışı: readonly=true OAuth scope'unu geçersiz kılar. Olmadan, salt okunur OAuth onay UI'sinde seçilen scope tarafından belirlenir.

Eski HTTP başlığı x-read-only de bir alternatif olarak desteklenir (sorgu parametresinden daha düşük öncelik).

Not: Salt okunur mod, hangi araçların kullanılabileceğini kısıtlar. Ayrıca, run_sql aracı yalnızca salt okunur sorgular için kullanılabilir kalır.

URL Sorgu Parametreleri Erişim Denetimi İçin

İzin bağlamı (kapsam kategorileri, proje kapsamı, salt okunur mod), MCP server URL'sinin URL sorgu parametreleri aracılığıyla yapılandırılır. Yapılandırma her istek ile birlikte seyahat eder ve hemen etkili olur — yeniden kimlik doğrulamaya gerek yoktur.

Parametre	Açıklama	Örnek
readonly	Salt okunur modu etkinleştir (true/false)	?readonly=true
category	Belirli araç kategorilerine kısıtla (tekrar veya CSV)	?category=querying&category=schema
projectId	Tüm işlemleri tek bir projeye kapsam al	?projectId=proj-123

Salt okunur + proje kapsamlı örnek:

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?readonly=true&projectId=my-project-id"
    }
  }
}

Kategori filtrelenmiş örnek (yalnızca querying ve schema araçları):

{
  "mcpServers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp?category=querying&category=schema"
    }
  }
}

/api/list-tools endpoint'ini kullanarak herhangi bir yapılandırma için hangi araçların görünür olduğunu önizleyebilirsiniz (kimlik doğrulaması gerekmez):

curl "https://mcp.neon.tech/api/list-tools?readonly=true&category=querying"

Salt okunur modda kullanılabilen araçlar

• list_projects, list_shared_projects, describe_project, list_organizations
• describe_branch, list_branch_computes, compare_database_schema
• run_sql, run_sql_transaction, get_database_tables, describe_table_schema
• list_slow_queries, explain_sql_statement
• get_connection_string
• search, fetch, list_docs_resources, get_doc_resource

Yazma erişimi gerektiren araçlar:

• create_project, delete_project
• create_branch, delete_branch, reset_from_parent
• provision_neon_auth, provision_neon_data_api
• prepare_database_migration, complete_database_migration
• prepare_query_tuning, complete_query_tuning

Server-Sent Events (SSE) Transport'ı (Kullanımdan Kaldırılmış)

MCP, iki uzak server transport'unu destekler: kullanımdan kaldırılan Server-Sent Events (SSE) ve daha yeni, önerilen Streamable HTTP. LLM client'ınız henüz Streamable HTTP'yi desteklemiyorsa, endpoint'i https://mcp.neon.tech/mcp adresinden https://mcp.neon.tech/sse adresine değiştirerek bunun yerine SSE'yi kullanabilirsiniz.

SSE transport'unu kullanarak çalışma alanınızdaki tüm algılanan agent'lar ve editörler için Neon MCP Server'ını eklemek üzere aşağıdaki komutu çalıştırın:

npx add-mcp https://mcp.neon.tech/sse --type sse

Uzak Server Mimarisi

Uzak server, Vercel'de mcp.neon.tech adresinde bir Next.js App Router uygulaması olarak çalışır.

[!NOTE] Kök / yolu Neon MCP Server dokümanlarına yönlendirilir. Bir açılış sayfası yoktur.

Temel uygulama alanları:

• landing/app/api/[transport]/route.ts: Streamable HTTP (/mcp) ve SSE (/sse) için MCP transport endpoint'i
• landing/app/api/authorize/, landing/app/callback/, landing/app/api/token/, landing/app/api/revoke/: OAuth akış endpoint'leri
• landing/app/.well-known/: OAuth keşif metaveri endpoint'leri
• landing/mcp-src/: MCP server, araçlar, işleyiciler, analitik ve Sentry entegrasyonu
• landing/lib/: Next.js uyumlu yardımcılar (OAuth, yapılandırma, hata işleme)
• landing/mcp-src/utils/read-only.ts: salt okunur mod ve kapsam işleme

Rehberler

• Neon MCP Server Rehberi
• MCP Client'larını Neon'a Bağlama
• Neon MCP Server ile Cursor
• Neon MCP Server ile Claude Desktop
• Neon MCP Server ile Cline
• Neon MCP Server ile Windsurf
• Neon MCP Server ile Zed

Özellikler

Desteklenen Araçlar

Neon MCP Server, aşağıdaki eylemleri sağlar ve bunlar MCP Client'larına "araçlar" olarak sunulur. Bu araçları kullanarak Neon projeleriniz ve veritabanlarınız ile doğal dil komutları aracılığıyla etkileşime girebilirsiniz.

Araç Kapsam Metaveri

Her araç tanımı, izin tabanlı araç filtreleme ve onay UX için kullanılan bir scope kategorisi içerir. Mevcut kategoriler:

• projects
• branches
• schema
• querying
• neon_auth
• data_api
• docs
• null (kapsam kategorisi olmayan araçlar)

Notlar:

• compare_database_schema schema altında kategorize edilir.
• provision_neon_data_api data_api altında kategorize edilir (neon_auth ayrı).
• Salt okunur yaptırım yine de readOnlySafe ve sunucu tarafı salt okunur mantığına dayanır; scope kategori metaveridir, bağımsız bir okuma/yazma anahtarı değildir.
• Proje kapsamlı modda (?projectId=...), search ve fetch kullanılamaz.

Proje Yönetimi:

• list_projects: Hesabınızdaki ilk 10 Neon projesini listeler ve her projenin bir özeti sağlar. Belirli bir proje bulamıyorsanız, limit parametresine daha yüksek bir değer geçerek limiti artırın.
• list_shared_projects: Mevcut kullanıcı ile paylaşılan Neon projelerini listeler. Bir arama parametresini ve döndürülecek projelerin sayısını sınırlamayı destekler (varsayılan: 10).
• describe_project: Belirli bir Neon projesi hakkında ID, adı ve ilişkili branch'ler ve veritabanları da dahil olmak üzere ayrıntılı bilgiler getirir.
• create_project: Neon hesabınızda yeni bir Neon projesi oluşturur. Proje, branch'ler, veritabanları, roller ve compute'ler için bir kapsayıcı görevi görmektedir.
• delete_project: Mevcut bir Neon projesini ve onunla ilişkili tüm kaynakları siler.
• list_organizations: Mevcut kullanıcının erişim sahibi olduğu tüm kuruluşları listeler. İsteğe bağlı olarak arama parametresini kullanarak kuruluş adına veya ID'sine göre filtreleyebilirsiniz.

Branch Yönetimi:

• create_branch: Belirli bir Neon projesi içinde yeni bir branch oluşturur. Geliştirme, test veya göçler için Neon'un branching özelliğinden yararlanır.
• delete_branch: Mevcut bir branch'i Neon projesinden siler.
• describe_branch: Belirli bir branch'in adı, ID'si ve ana branch'i gibi ayrıntılarını alır.
• list_branch_computes: Bir proje veya belirli bir branch için compute endpoint'lerini listeler; compute ID'si, türü, boyutu, son aktif saati ve otomatik ölçeklendirme bilgilerini de içerir.
• compare_database_schema: Alt branch ile ana branch'i arasında şema farkını gösterir
• reset_from_parent: Mevcut branch'i ana branch'inin durumuna sıfırlar, yerel değişiklikleri atar. Branch'in alt branch'leri varsa otomatik olarak yedek olarak saklar veya özel bir ad ile istenirse isteğe bağlı olarak korur.

SQL Sorgusu Yürütme:

• get_connection_string: Veritabanı bağlantı dizesini döndürür.
• run_sql: Belirli bir Neon veritabanında tek bir SQL sorgusu yürütür. Hem okuma hem yazma işlemlerini destekler.
• run_sql_transaction: Neon veritabanında tek bir transaction içinde bir dizi SQL sorgusu yürütür.
• get_database_tables: Belirli bir Neon veritabanı içindeki tüm tabloları listeler.
• describe_table_schema: Belirli bir tablonun şema tanımını alır; sütunları, veri türlerini ve kısıtlamaları detaylandırır.

Veritabanı Göçleri (Şema Değişiklikleri):

• prepare_database_migration: Veritabanı göçü işlemini başlatır. Önemlisi, migration'ı ana branch'i etkilemeden önce güvenli bir şekilde uygulamak ve test etmek için geçici bir branch oluşturur.
• complete_database_migration: Hazırlanmış bir veritabanı göçünü sonlandırır ve ana branch'e uygular. Bu işlem, geçici göç branch'inden değişiklikleri birleştirir ve geçici kaynakları temizler.

SQL Sorgulama ve Optimizasyon:

• list_slow_queries: Bir veritabanındaki en yavaş sorguları bularak performans darboğazlarını tanımlar. pg_stat_statements uzantısını gerektirir.
• explain_sql_statement: SQL sorguları için ayrıntılı yürütme planları sağlayarak performans darboğazlarını belirlemeye yardımcı olur.
• prepare_query_tuning: Sorgu performansını analiz eder ve dizin oluşturma gibi optimizasyonlar önerir. Bu optimizasyonları güvenli bir şekilde test etmek için geçici bir branch oluşturur.
• complete_query_tuning: Sorgu ayarını, optimizasyonları ana branch'e uygulayarak veya atarak sonlandırır. Geçici ayar branch'ini temizler.

Neon Auth:

• provision_neon_auth: Neon Auth'u Neon projesi için hazırlar. Geliştiricilerin bir Auth sağlayıcı ile bir entegrasyon oluşturarak kimlik doğrulama altyapısını kolayca kurmasına olanak tanır.

Neon Data API:

• provision_neon_data_api: HTTP tabanlı veritabanı erişimi için Neon Data API'sini Neon Auth veya harici JWKS sağlayıcıları aracılığıyla isteğe bağlı JWT kimlik doğrulamasıyla hazırlar.

Arama ve Keşif:

• search: Sorgu ile eşleşen kuruluşlar, projeler ve branch'leri arar. Neon Console'e doğrudan bağlantılar ile ID'ler ve başlıklar döndürür.
• fetch: Bir ID kullanarak (genellikle arama aracından) belirli bir kuruluş, proje veya branch'in ayrıntılı bilgilerini getirir.

Dokümantasyon ve Kaynaklar:

• list_docs_resources: https://neon.com/docs/llms.txt adresinden dizini getirerek tüm kullanılabilen Neon dokümantasyon sayfalarını listeler. get_doc_resource aracı kullanılarak tek tek getirme yapılabilecek sayfa URL'lerini ve başlıklarını döndürür.
• get_doc_resource: Belirli bir Neon dokümantasyon sayfasını markdown içeriği olarak getirir. Kullanılabilen sayfa slug'larını keşfetmek için önce list_docs_resources aracını kullanın, ardından slug'ı bu aracına geçirin.

Göçler

Göçler, veritabanı şemanızdaki değişiklikleri zaman içinde yönetmenin bir yoludur. Neon MCP server'ı ile, LLM'ler ayrı "Başla" (prepare_database_migration) ve "Tamamla" (complete_database_migration) komutları ile göçleri güvenli bir şekilde yapabilirler.

"Başla" komutu bir göç kabul eder ve bunu yeni bir geçici branch'te çalıştırır. Dönüş üzerine, bu komut LLM'ye migration'ı bu branch