Neon MCP Server

resmi

Interact with the Neon serverless Postgres platform

Dokümantasyon

Neon MCP Sunucusu

Neon MCP Sunucusu, Neon Postgres veritabanlarınızla doğal dilde etkileşim kurmanızı sağlayan açık kaynaklı bir araçtır.

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

Neon'un MCP sunucusu, doğal dil istekleri ile Neon API arasında bir köprü görevi görür. MCP üzerine inşa edilmiş olup, isteklerinizi gerekli API çağrılarına dönüştürerek proje ve dal oluşturma, sorgu çalıştırma ve veritabanı geçişlerini sorunsuz bir şekilde gerçekleştirme gibi görevleri yönetmenizi sağlar.

Neon MCP sunucusunun bazı temel özellikleri şunlardır:

Doğal dil etkileşimi: Neon veritabanlarını sezgisel, konuşma diline dayalı komutlarla yönetin.
Basitleştirilmiş veritabanı yönetimi: SQL yazmadan veya doğrudan Neon API'yi kullanmadan karmaşık eylemler gerçekleştirin.
Geliştirici olmayanlar için erişilebilirlik: Farklı teknik altyapılara sahip kullanıcıların Neon veritabanlarıyla etkileşim kurmasını sağlayın.
Veritabanı geçiş desteği: Doğal dil aracılığıyla başlatılan veritabanı şeması değişiklikleri için Neon'un dallanma yeteneklerinden yararlanın.

Örneğin, Claude Code'da veya herhangi bir MCP İstemcisinde, Neon ile aşağıdakiler gibi işlemleri doğal dil kullanarak gerçekleştirebilirsiniz:

Let's create a new Postgres database, and call it "my-database". Let's then create a table called users with the following columns: id, name, email, and password.
I want to run a migration on my project called "my-project" that alters the users table to add a new column called "created_at".
Can you give me a summary of all of my Neon projects and what data is in each one?

[!WARNING]
Neon MCP Sunucusu Güvenlik Hususları
Neon MCP Sunucusu, doğal dil istekleri aracılığıyla güçlü veritabanı yönetim yetenekleri sunar. LLM tarafından talep edilen eylemleri yürütmeden önce her zaman gözden geçirin ve yetkilendirin. Neon MCP Sunucusuna yalnızca yetkili kullanıcıların ve uygulamaların erişebildiğinden emin olun.

Neon MCP Sunucusu yalnızca yerel geliştirme ve IDE entegrasyonları için tasarlanmıştır. Neon MCP Sunucusunu üretim ortamlarında kullanmanızı önermiyoruz. Kazara veya yetkisiz değişikliklere yol açabilecek güçlü işlemler gerçekleştirebilir.

Daha fazla bilgi için MCP güvenlik kılavuzuna → bakın.

Neon MCP Sunucusunu Kurma

Neon MCP Sunucusunu kurmak için birkaç seçenek vardır:

API Anahtarı ile Hızlı Kurulum (Cursor, VS Code ve Claude Code): Neon'un MCP Sunucusunu, aracı becerilerini ve VS Code uzantısını tek bir komutla otomatik olarak yapılandırmak için neonctl@latest init komutunu çalıştırın.
Uzak MCP Sunucusu (OAuth Tabanlı Kimlik Doğrulama): Kimlik doğrulama için OAuth kullanarak Neon'un yönetilen MCP sunucusuna bağlanın. Bu yöntem, API anahtarlarını yönetme ihtiyacını ortadan kaldırdığı için daha kullanışlıdır. Ayrıca, en son özellikleri ve iyileştirmeleri yayınlanır yayınlanmaz otomatik olarak alırsınız.
Uzak MCP Sunucusu (API Anahtarı Tabanlı Kimlik Doğrulama): Kimlik doğrulama için API anahtarı kullanarak Neon'un yönetilen MCP sunucusuna bağlanın. Bu yöntem, OAuth'un mevcut olmadığı durumlarda uzak bir aracıyı Neon'a bağlamak istediğinizde kullanışlıdır. Ayrıca, en son özellikleri ve iyileştirmeleri yayınlanır yayınlanmaz otomatik olarak alırsınız.

Ön Koşullar

Bir MCP İstemci 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

Manuel olarak bir API anahtarı oluşturmak istemiyor musunuz?

Neon'un MCP Sunucusunu tek bir 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ğrulaması yapacak, sizin için bir Neon API anahtarı oluşturacak ve düzenleyicinizi otomatik olarak yapılandıracaktır.

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

Kimlik doğrulama için OAuth kullanarak Neon'un yönetilen MCP sunucusuna bağlanın. Bu en kolay kurulumdur, bu sunucunun yerel kurulumunu gerektirmez ve istemcide bir Neon API anahtarı yapılandırılmasına ihtiyaç duymaz.

Çalışma alanınızdaki tüm algılanan aracılar ve düzenleyiciler için Neon MCP Sunucusunu eklemek üzere aşağıdaki komutu çalıştırın:

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

Neon MCP Sunucusunu proje kapsamlı yerine genel MCP sunucu listesine eklemek için -g bayrağını ekleyin.

Alternatif olarak, istemcinizin MCP sunucu yapılandırma dosyasına (örn. mcp.json, mcp_config.json) aşağıdaki "Neon" girdisini ekleyebilirsiniz:

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

Kiro: Kiro MCP yapılandırma dosyanıza (genel için ~/.kiro/settings/mcp.json veya proje kapsamlı için .kiro/settings/mcp.json) aşağıdakini ekleyin:

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

Veya bu README'nin üst kısmındaki tek tıklamayla kurulum düğmesini kullanın. Daha fazla bilgi için Kiro MCP belgelerine bakın.

MCP istemcinizi yeniden başlatın veya yenileyin.
Tarayıcınızda bir OAuth penceresi açılacaktır. MCP istemcinizin Neon hesabınıza erişmesine izin vermek için yönergeleri izleyin.

OAuth tabanlı kimlik doğrulamada, MCP sunucusu varsayılan olarak kişisel Neon hesabınız altındaki projeler üzerinde çalışacaktır. Bir organizasyona ait projelere erişmek veya bunları yönetmek için, MCP istemcisine yapacağınız istemde açıkça org_id veya project_id sağlamanız gerekir.

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

Uzak MCP Sunucusu, istemciniz destekliyorsa Authorization başlığında bir API anahtarı kullanarak kimlik doğrulamayı da destekler.

Neon Konsolu'nda bir Neon API anahtarı oluşturun. Ardından, çalışma alanınızdaki tüm algılanan aracılar ve düzenleyiciler için Neon MCP Sunucusunu 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, istemcinizin MCP sunucu yapılandırma dosyasına (örn. mcp.json, mcp_config.json) aşağıdaki "Neon" girdisini ekleyebilirsiniz:

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

Erişimi yalnızca organizasyon altındaki projelerle sınırlamak için bir organizasyonun API anahtarını sağlayın.

Kapsamlar ve Salt Okunur Mod

Neon MCP, read, write ve * (* her ikisi anlamına gelir) OAuth kapsamlarını destekler. MCP istemciniz bu kapsamları doğrudan talep edebilir veya seçimi OAuth izinleri kullanıcı arayüzünde yapabilirsiniz.

Salt okunur mod, hangi araçların kullanılabilir olduğunu kısıtlayarak proje oluşturma, dal oluşturma veya geçiş çalıştırma gibi yazma işlemlerini devre dışı bırakır. Salt okunur araçlar arasında projeleri listeleme, şemaları tanımlama, veri sorgulama ve performans metriklerini görüntüleme bulunur.

Salt okunur modu iki şekilde ayarlayabilirsiniz:

OAuth kapsam seçimi (önerilir): OAuth'ta, yetkilendirme kullanıcı arayüzünde Tam erişim seçeneğinin işaretini kaldırarak salt okunur'u seçin.
readonly sorgu parametresi: MCP sunucu URL'nize ?readonly=true ekleyin:

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

Sorgu parametresinin davranışı:

API anahtarı akışı: readonly=true, salt okunur modu etkinleştirmenin yoludur (bu akışta OAuth kapsam değişimi yoktur).
OAuth akışı: readonly=true, OAuth kapsamını geçersiz kılar. Bu olmadan, salt okunur, OAuth onay kullanıcı arayüzünde seçilen kapsam tarafından belirlenir.

Eski HTTP başlığı x-read-only da bir geri dönüş olarak desteklenir (sorgu parametresinden daha düşük öncelikli).

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

Erişim Kontrolü için URL Sorgu Parametreleri

Yetki bağlamı (kapsam kategorileri, proje kapsamı, salt okunur mod), MCP sunucu URL'sindeki URL sorgu parametreleri aracılığıyla yapılandırılır. Yapılandırma her istekle birlikte gelir ve hemen etkili olur — yeniden kimlik doğrulama gerekmez.

Parametre	Açıklama	Örnek
`readonly`	Salt okunur modu etkinleştir (`true`/`false`)	`?readonly=true`
`category`	Belirli araç kategorileriyle sınırla (tekrarlı veya CSV)	`?category=querying&category=schema`
`projectId`	Tüm işlemleri tek bir projeyle kapsamlandır	`?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 sorgulama ve şema araçları):

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

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

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

Salt okunur modda kullanılabilir 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

Sunucu Tarafından Gönderilen Olaylar (SSE) Aktarımı (Kullanımdan Kaldırıldı)

MCP iki uzak sunucu aktarımını destekler: kullanımdan kaldırılan Sunucu Tarafından Gönderilen Olaylar (SSE) ve daha yeni, önerilen Akışkan HTTP. LLM istemciniz henüz Akışkan HTTP'yi desteklemiyorsa, bunun yerine SSE kullanmak için uç noktayı https://mcp.neon.tech/mcp yerine https://mcp.neon.tech/sse olarak değiştirebilirsiniz.

SSE aktarımını kullanarak çalışma alanınızdaki tüm algılanan aracılar ve düzenleyiciler için Neon MCP Sunucusunu eklemek üzere aşağıdaki komutu çalıştırın:

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

Uzak Sunucu Mimarisi

Uzak sunucu, mcp.neon.tech adresinde Vercel üzerinde bir Next.js App Router uygulaması olarak çalışır.

[!NOTE] Kök / yolu Neon MCP Sunucusu belgelerine yönlendirir. Bir açılış sayfası yoktur.

Temel uygulama alanları:

landing/app/api/[transport]/route.ts: Akışkan HTTP (/mcp) ve SSE (/sse) için MCP aktarım uç noktası
landing/app/api/authorize/, landing/app/callback/, landing/app/api/token/, landing/app/api/revoke/: OAuth akış uç noktaları
landing/app/.well-known/: OAuth keşif meta veri uç noktaları
landing/mcp-src/: MCP sunucusu, 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

Kılavuzlar

Özellikler

Desteklenen Araçlar

Neon MCP Sunucusu, MCP İstemcilerine "araçlar" olarak sunulan aşağıdaki eylemleri sağlar. Bu araçları, doğal dil komutlarını kullanarak Neon projeleriniz ve veritabanlarınızla etkileşim kurmak için kullanabilirsiniz.

Araç Kapsam Meta Verisi

Her araç tanımı, yetki tabanlı araç filtreleme ve onay kullanıcı deneyimi için kullanılan bir scope kategorisi içerir. Mevcut kategoriler şunlardır:

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

Notlar:

compare_database_schema, schema altında kategorize edilmiştir.
provision_neon_data_api, data_api altında kategorize edilmiştir (neon_auth'ten ayrı).
Salt okunur zorunluluğu hala readOnlySafe ve sunucu tarafı salt okunur mantığına dayanır; scope kategori meta verisidir, 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 özetini sunar. Belirli bir projeyi bulamazsanız, limit parametresine daha yüksek bir değer ileterek limiti artırın.
list_shared_projects: Mevcut kullanıcıyla paylaşılan Neon projelerini listeler. Bir arama parametresi ve döndürülen proje sayısını sınırlamayı destekler (varsayılan: 10).
describe_project: Belirli bir Neon projesi hakkında, kimliği, adı ve ilişkili dallar ile veritabanları dahil olmak üzere ayrıntılı bilgi getirir.
create_project: Neon hesabınızda yeni bir Neon projesi oluşturur. Bir proje; dallar, veritabanları, roller ve hesaplamalar için bir kapsayıcı görevi görür.
delete_project: Mevcut bir Neon projesini ve onunla ilişkili tüm kaynakları siler.
list_organizations: Mevcut kullanıcının erişimine sahip olduğu tüm organizasyonları listeler. Arama parametresini kullanarak isteğe bağlı olarak organizasyon adına veya kimliğine göre filtreleyin.

Dal Yönetimi:

create_branch: Belirtilen bir Neon projesi içinde yeni bir dal oluşturur. Geliştirme, test veya geçişler için Neon'un dallanma özelliğinden yararlanır.
delete_branch: Bir Neon projesinden mevcut bir dalı siler.
describe_branch: Belirli bir dal hakkında adı, kimliği ve üst dalı gibi ayrıntıları getirir.
list_branch_computes: Bir proje veya belirli bir dal için hesaplama uç noktalarını listeler; hesaplama kimliği, türü, boyutu, son aktif olma zamanı ve otomatik ölçeklendirme bilgilerini içerir.
compare_database_schema: Alt dal ile üst dalı arasındaki şema farkını gösterir.
reset_from_parent: Mevcut dalı, yerel değişiklikleri atarak üst dalının durumuna sıfırlar. Dalın alt dalları varsa otomatik olarak yedeklemeye korur veya istek üzerine özel bir adla isteğe bağlı olarak korur.

SQL Sorgu Çalıştırma:

get_connection_string: Veritabanı bağlantı dizenizi döndürür.
run_sql: Belirtilen bir Neon veritabanına karşı tek bir SQL sorgusu çalıştırır. Hem okuma hem de yazma işlemlerini destekler.
run_sql_transaction: Bir Neon veritabanına karşı tek bir işlem içinde bir dizi SQL sorgusu çalıştırır.
get_database_tables: Belirtilen bir Neon veritabanındaki tüm tabloları listeler.
describe_table_schema: Belirli bir tablonun şema tanımını getirir; sütunları, veri türlerini ve kısıtlamaları detaylandırır.

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

prepare_database_migration: Bir veritabanı geçiş sürecini başlatır. Kritik olarak, geçişi ana dalı etkilemeden önce güvenli bir şekilde uygulamak ve test etmek için geçici bir dal oluşturur.
complete_database_migration: Hazırlanan bir veritabanı geçişini ana dala sonlandırır ve uygular. Bu eylem, geçici geçiş dalındaki 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ı belirler. pg_stat_statements uzantısını gerektirir.
explain_sql_statement: Performans darboğazlarını belirlemeye yardımcı olmak için SQL sorguları için ayrıntılı yürütme planları sağlar.
prepare_query_tuning: Sorgu performansını analiz eder ve indeks oluşturma gibi optimizasyonlar önerir. Bu optimizasyonları güvenli bir şekilde test etmek için geçici bir dal oluşturur.
complete_query_tuning: Optimizasyonları ana dala uygulayarak veya atarak sorgu ayarlamayı sonlandırır. Geçici ayarlama dalını temizler.

Neon Auth:

provision_neon_auth: Bir Neon projesi için Neon Auth sağlar. Geliştiricilerin bir Auth sağlayıcısıyla entegrasyon oluşturarak kimlik doğrulama altyapısını kolayca kurmalarına olanak tanır.

Neon Data API:

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

Arama ve Keşif:

search: Bir sorguyla eşleşen organizasyonlar, projeler ve dallar arasında arama yapar. Kimlikleri, başlıkları ve Neon Konsolu'na doğrudan bağlantıları döndürür.
fetch: Bir kimlik kullanarak (genellikle arama aracından) belirli bir organizasyon, proje veya dal hakkında ayrıntılı bilgi getirir.

Dokümantasyon ve Kaynaklar:

list_docs_resources: https://neon.com/docs/llms.txt adresinden dizini getirerek mevcut tüm Neon dokümantasyon sayfalarını listeler. get_doc_resource aracı kullanılarak tek tek getirilebilecek 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. Önce mevcut sayfa kısa adlarını keşfetmek için list_docs_resources aracını kullanın, ardından kısa adı bu araca iletin.

Geçişler

Geçişler, veritabanı şemanızdaki değişiklikleri zaman içinde yönetmenin bir yoludur. Neon MCP sunucusu ile, LLM'ler ayrı "Başlat" (prepare_database_migration) ve "İşle" (complete_database_migration) komutlarıyla geçişleri güvenli bir şekilde yapma yetkisine sahiptir.

"Başlat" komutu bir geçişi kabul eder ve onu yeni bir geçici dalda çalıştırır. Geri döndüğünde, bu komut LLM'ye geçişi bu dalda test etmesi gerektiğini ima eder. LLM daha sonra geçişi orijinal dala uygulamak için "İşle" komutunu çalıştırabilir.

Geliştirme

Bu proje, paket yöneticisi olarak Corepack aracılığıyla sabitlenmiş pnpm kullanır.

Proje Yapısı

MCP sunucu kodu, mcp.neon.tech adresinde Vercel'e dağıtılan bir Next.js uygulaması olan landing/ dizininde bulunur.

cd landing
corepack enable
pnpm install

Yerel Geliştirme

# Start the Next.js dev server (for the remote MCP server)
pnpm run dev

Lint ve Tip Kontrolü

pnpm run lint
pnpm run typecheck

Ortam Değişkenleri

Uzak sunucu çalışma zamanı için gereklidir:

Değişken	Açıklama
`SERVER_HOST`	Sunucu URL'si (varsayılan: `VERCEL_URL`)
`UPSTREAM_OAUTH_HOST`	Neon OAuth sağlayıcı URL'si
`CLIENT_ID`	OAuth istemci kimliği
`CLIENT_SECRET`	OAuth istemci sırrı
`COOKIE_SECRET`	İmzalı çerezler için sır
`KV_URL`	Vercel KV (Upstash Redis) URL'si
`OAUTH_DATABASE_URL`	Belirteç depolama için Postgres URL'si

İsteğe bağlı:

Değişken	Açıklama
`LOG_LEVEL`	Winston günlük seviyesi: `error`, `warn`, `info` (varsayılan), `debug`, `verbose`, `silly`

Test Piramidi

Tüm testler landing/ konumundan çalıştırılır.

cd landing

# Unit tests
pnpm run test:unit

# Integration tests
pnpm run test:integration

# MCP protocol end-to-end tests (real MCP client/server tool calls)
pnpm run test:e2e:mcp

# Website end-to-end tests (Playwright; provisions/validates ephemeral DB first)
pnpm run test:e2e:web

# Full end-to-end suite
pnpm run test:e2e

# Full test pyramid (unit + integration + e2e; used in CI)
pnpm run test

Test stratejisi:

Aktarım/protokol ve kullanıcı tarafından görülebilen davranışlar için E2E'yi tercih edin.
Belirleyici araç sözleşmeleri ve iş akışı davranışı için entegrasyon testlerini kullanın.
Saf mantık ve uç durumlar için birim testlerini kullanın.
Birleştirme kapısı testlerinde üçüncü taraf çalışma süresine güvenmekten kaçının; entegrasyon/birim katmanlarında harici bağımlılıkları taklit edin.

Dağıtım

Vercel, depo dalı yapılandırmasından uzak sunucuyu otomatik olarak dağıtır. Çekme istekleri için önizleme ortamları mevcuttur.