Query | Supabase için MCP sunucusu

🌅 pypi üzerinden 17.000'den fazla kurulum ve Smithery.ai'de 30.000'e yakın indirilme — kısacası çok eğlenceliydi! 🥳 Bu sunucuyu geçtiğimiz birkaç ay boyunca kullanan herkese teşekkürler ve umarım sizin için faydalı olmuştur. Supabase kendi resmi MCP sunucusunu yayınladığından beri, bu sunucuyu artık aktif olarak geliştirmemeye karar verdim. Resmi MCP sunucusu aynı derecede özellik açısından zengin ve gelecekte daha birçok özellik eklenecektir. Kontrol etmeye değer!

Query MCP, IDE'nizin SQL çalıştırmasını, şema değişikliklerini yönetmesini, Supabase Management API'sini çağırmasını ve Auth Admin SDK'yı kullanmasını — tümü yerleşik güvenlik kontrolleriyle — güvenli bir şekilde yapmasını sağlayan açık kaynaklı bir MCP sunucusudur.

İçindekiler

Başlamak • Özellik özeti • Sorun giderme • Changelog

✨ Temel özellikler

• 💻 Cursor, Windsurf, Cline ve stdio protokolünü destekleyen diğer MCP istemcileriyle uyumlu
• 🔐 SQL sorgu yürütmesinin salt okunur ve okuma-yazma modlarını kontrol edin
• 🔍 Risk düzeyi değerlendirmesi ile çalışma zamanı SQL sorgu doğrulaması
• 🛡️ SQL işlemleri için üç katmanlı güvenlik sistemi: güvenli, yazma ve yıkıcı
• 🔄 Doğrudan ve havuzlu veritabanı bağlantıları için sağlam işlem yönetimi
• 📝 Veritabanı şema değişikliklerinin otomatik sürümlendirilmesi
• 💻 Supabase Management API ile Supabase projelerinizi yönetin
• 🧑‍💻 Supabase Auth Admin yöntemlerini Python SDK ile kullanıcıları yönetin
• 🔨 Cursor & Windsurf'ün MCP ile daha etkili çalışmasına yardımcı olmak için önceden oluşturulmuş araçlar
• 📦 Paket yöneticisi aracılığıyla çok basit kurulum ve ayarlama (uv, pipx, vb.)

Başlamak

Ön koşullar

Sunucuyu kurmak sisteminizde aşağıdakileri gerektirir:

• Python 3.12+

uv üzerinden kurmayı planlıyorsanız, yüklü olduğundan emin olun.

PostgreSQL Kurulumu

PostgreSQL kurulumu artık MCP sunucusunun kendisi için gerekli değildir, çünkü artık PostgreSQL geliştirme kütüphanelerine bağlı olmayan asyncpg kullanır.

Ancak, yerel bir Supabase örneğini çalıştırıyorsanız PostgreSQL'e ihtiyacınız olacaktır:

MacOS

brew install postgresql@16

Windows

• PostgreSQL 16+ dosyasını https://www.postgresql.org/download/windows/ adresinden indirin ve kurun
• Kurulum sırasında "PostgreSQL Server" ve "Command Line Tools" seçeneğinin işaretli olduğundan emin olun

Adım 1. Kurulum

v0.2.0'dan beri paket kurulumu desteği sundum. Aşağıdakilerden birini kullanarak sunucuyu paket yöneticisi aracılığıyla kurabilirsiniz:

# pipx yüklüyse (önerilir)
pipx install supabase-mcp-server

# uv yüklüyse
uv pip install supabase-mcp-server

pipx önerilir çünkü her paket için izole ortamlar oluşturur.

Ayrıca sunucuyu depo klonlayarak ve kök dizinden pipx install -e . çalıştırarak manuel olarak yükleyebilirsiniz.

Kaynaktan yükleme

Örneğin yerel geliştirme için kaynaktan yüklemek istiyorsanız:

uv venv
# Mac üzerinde
source .venv/bin/activate
# Windows üzerinde
.venv\Scripts\activate
# Paketi düzenlenebilir modda kurun
uv pip install -e .

Smithery.ai üzerinden yükleme

Bu MCP sunucusuna bağlanmak için Smithery.ai nasıl kullanılacağına dair tüm talimatları burada bulabilirsiniz.

Adım 2. Yapılandırma

Supabase MCP sunucusu, Supabase veritabanınıza bağlanmak, Management API'sine erişmek ve Auth Admin SDK'yı kullanmak için yapılandırma gerektirir. Bu bölüm tüm mevcut yapılandırma seçeneklerini ve bunları nasıl ayarlayacağınızı açıklar.

🔑 Önemli: v0.4'ten beri MCP sunucusu bu MCP sunucusunu kullanmak için thequery.dev adresinden ücretsiz olarak alabilir bir API anahtarı gerektirmektedir.

Ortam Değişkenleri

Sunucu aşağıdaki ortam değişkenlerini kullanır:

Değişken	Gerekli	Varsayılan	Açıklama
SUPABASE_PROJECT_REF	Evet	127.0.0.1:54322	Supabase proje referans kimliğiniz (veya yerel host:port)
SUPABASE_DB_PASSWORD	Evet	postgres	Veritabanı parolanız
SUPABASE_REGION	Evet*	us-east-1	Supabase projenizin barındırıldığı AWS bölgesi
SUPABASE_ACCESS_TOKEN	Hayır	Yok	Supabase Management API için kişisel erişim token'ı
SUPABASE_SERVICE_ROLE_KEY	Hayır	Yok	Auth Admin SDK için hizmet rolü anahtarı
QUERY_API_KEY	Evet	Yok	thequery.dev adresinden API anahtarı (tüm işlemler için gerekli)

Not: Varsayılan değerler yerel Supabase geliştirmesi için yapılandırılmıştır. Uzak Supabase projeleri için SUPABASE_PROJECT_REF ve SUPABASE_DB_PASSWORD için kendi değerlerinizi sağlamanız gerekir.

🚨 KRİTİK YAPILANDIRMA NOTU: Uzak Supabase projeleri için, SUPABASE_REGION kullanarak projenizin barındırıldığı doğru bölgeyi AYNI ŞEKILDE belirtmelisiniz. "Tenant or user not found" hatası alırsanız, bu neredeyse kesin olarak bölge ayarınızın projenizin gerçek bölgesiyle eşleşmemesi nedeniyledir. Proje bölgenizi Supabase dashboard'unda Project Settings altında bulabilirsiniz.

Bağlantı Türleri

Veritabanı Bağlantısı

• Sunucu, işlem pooler endpoint'ini kullanarak Supabase PostgreSQL veritabanınıza bağlanır
• Yerel geliştirme 127.0.0.1:54322 adresine doğrudan bağlantı kullanır
• Uzak projeler şu formatı kullanır: postgresql://postgres.[project_ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres

⚠️ Önemli: Oturum pooling bağlantıları desteklenmiyor. Sunucu, MCP sunucusu mimarisiyle daha iyi uyumluluk için yalnızca işlem pooling kullanır.

Management API Bağlantısı

• SUPABASE_ACCESS_TOKEN ayarlanmasını gerektirir
• Supabase Management API'sine https://api.supabase.com adresinden bağlanır
• Yalnızca uzak Supabase projeleriyle çalışır (yerel geliştirme ile değil)

Auth Admin SDK Bağlantısı

• SUPABASE_SERVICE_ROLE_KEY ayarlanmasını gerektirir
• Yerel geliştirme için http://127.0.0.1:54321 adresine bağlanır
• Uzak projeler için https://[project_ref].supabase.co adresine bağlanır

Yapılandırma Yöntemleri

Sunucu yapılandırmayı bu sırayla arar (en yüksekten en düşüğe öncelik):

1. Ortam Değişkenleri: Doğrudan ortamınızda ayarlanan değerler
2. Yerel .env Dosyası: Mevcut çalışma dizininizde bir .env dosyası (yalnızca kaynaktan çalıştırırken çalışır)
3. Global Yapılandırma Dosyası:
   • Windows: %APPDATA%\supabase-mcp\.env
   • macOS/Linux: ~/.config/supabase-mcp/.env
4. Varsayılan Ayarlar: Yerel geliştirme varsayılanları (başka yapılandırma bulunamazsa)

⚠️ Önemli: pipx veya uv aracılığıyla kurulan paket kullanırken, proje dizininizdeki yerel .env dosyaları algılanmaz. Ortam değişkenlerini veya global yapılandırma dosyasını kullanmanız gerekir.

Yapılandırma Ayarlama

Seçenek 1: İstemciye Özgü Yapılandırma (Önerilir)

Ortam değişkenlerini doğrudan MCP istemci yapılandırmanızda ayarlayın (Adım 3'teki istemciye özgü kurulum talimatlarına bakınız). Çoğu MCP istemcisi bu yaklaşımı destekler; bu, yapılandırmanızı istemci ayarlarınızla tutar.

Seçenek 2: Global Yapılandırma

Tüm MCP sunucusu örnekleri tarafından kullanılacak global bir .env yapılandırma dosyası oluşturun:

# Yapılandırma dizini oluşturun
# macOS/Linux üzerinde
mkdir -p ~/.config/supabase-mcp
# Windows üzerinde (PowerShell)
mkdir -Force "$env:APPDATA\supabase-mcp"

# .env dosyasını oluşturun ve düzenleyin
# macOS/Linux üzerinde
nano ~/.config/supabase-mcp/.env
# Windows üzerinde (PowerShell)
notepad "$env:APPDATA\supabase-mcp\.env"

Dosyaya yapılandırma değerlerinizi ekleyin:

QUERY_API_KEY=your-api-key
SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_DB_PASSWORD=your-db-password
SUPABASE_REGION=us-east-1
SUPABASE_ACCESS_TOKEN=your-access-token
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

Seçenek 3: Projeye Özgü Yapılandırma (Yalnızca Kaynak Kurulumu)

Sunucuyu kaynaktan çalıştırıyorsanız (paket aracılığıyla değil), proje dizininizde aynı formatı kullanarak bir .env dosyası oluşturabilirsiniz.

Supabase Proje Bilgilerinizi Bulma

• Proje Referansı: Supabase proje URL'nizde bulunur: https://supabase.com/dashboard/project/<project-ref>
• Veritabanı Parolası: Proje oluşturma sırasında ayarlanır veya Project Settings → Database içinde bulunur
• Erişim Token'ı: https://supabase.com/dashboard/account/tokens adresinde oluşturun
• Hizmet Rolü Anahtarı: Project Settings → API → Project API keys içinde bulunur

Desteklenen Bölgeler

Sunucu tüm Supabase bölgelerini destekler:

• us-west-1 - West US (North California)
• us-east-1 - East US (North Virginia) - varsayılan
• us-east-2 - East US (Ohio)
• ca-central-1 - Canada (Central)
• eu-west-1 - West EU (Ireland)
• eu-west-2 - West Europe (London)
• eu-west-3 - West EU (Paris)
• eu-central-1 - Central EU (Frankfurt)
• eu-central-2 - Central Europe (Zurich)
• eu-north-1 - North EU (Stockholm)
• ap-south-1 - South Asia (Mumbai)
• ap-southeast-1 - Southeast Asia (Singapore)
• ap-northeast-1 - Northeast Asia (Tokyo)
• ap-northeast-2 - Northeast Asia (Seoul)
• ap-southeast-2 - Oceania (Sydney)
• sa-east-1 - South America (São Paulo)

Sınırlamalar

• Kendi Barındırma Desteği Yok: Sunucu yalnızca resmi Supabase.com barındırılan projeleri ve yerel geliştirmeyi destekler
• Connection String Desteği Yok: Özel connection string'leri desteklenmez
• Session Pooling Yok: Veritabanı bağlantıları için yalnızca işlem pooling desteklenir
• API ve SDK Özellikleri: Management API ve Auth Admin SDK özellikleri yalnızca uzak Supabase projeleriyle çalışır; yerel geliştirme ile değil

Adım 3. Kullanım

Genel olarak stdio protokolünü destekleyen herhangi bir MCP istemcisi bu MCP sunucusuyla çalışmalıdır. Bu sunucu aşağıdakilerle açıkça test edilmiştir:

• Cursor
• Windsurf
• Cline
• Claude Desktop

Ek olarak, smithery.ai'yi kullanarak bu sunucuyu yukarıdakiler dahil olmak üzere birçok istemcide yükleyebilirsiniz.

İstemcinizde bu MCP sunucusunu yüklemek için aşağıdaki kılavuzları izleyin.

Cursor

Settings -> Features -> MCP Servers'e gidin ve bu yapılandırmayla yeni bir sunucu ekleyin:

# herhangi bir ada ayarlanabilir
name: supabase
type: command
# pipx ile yüklediyseniz
command: supabase-mcp-server
# uv ile yüklediyseniz
command: uv run supabase-mcp-server
# yukarıdaki çalışmazsa, tam yolu kullanın (önerilir)
command: /full/path/to/supabase-mcp-server  # 'which supabase-mcp-server' (macOS/Linux) veya 'where supabase-mcp-server' (Windows) ile bulun

Yapılandırma doğruysa, yeşil bir nokta göstergesi ve sunucu tarafından sunulan araçların sayısını göreceksiniz.

Windsurf

Cascade -> çekiç simgesine tıklayın -> Yapılandır -> Yapılandırmayı doldurun:

{
    "mcpServers": {
      "supabase": {
        "command": "/Users/username/.local/bin/supabase-mcp-server",  // yolu güncelleyin
        "env": {
          "QUERY_API_KEY": "your-api-key",  // Gerekli - API anahtarınızı thequery.dev adresinden alın
          "SUPABASE_PROJECT_REF": "your-project-ref",
          "SUPABASE_DB_PASSWORD": "your-db-password",
          "SUPABASE_REGION": "us-east-1",  // isteğe bağlı, varsayılan us-east-1
          "SUPABASE_ACCESS_TOKEN": "your-access-token",  // isteğe bağlı, management API için
          "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"  // isteğe bağlı, Auth Admin SDK için
        }
      }
    }
}

Yapılandırma doğruysa, yeşil nokta göstergesi ve mevcut sunucular listesinde tıklanabilir supabase sunucusu göreceksiniz.

Claude Desktop

Claude Desktop ayrıca JSON yapılandırması aracılığıyla MCP sunucularını destekler. Supabase MCP sunucusunu ayarlamak için bu adımları izleyin:

1. Yürütülebilire tam yol bulun (bu adım kritiktir):

   # macOS/Linux üzerinde
   which supabase-mcp-server
   
   # Windows üzerinde
   where supabase-mcp-server
   

   Döndürülen tam yolu kopyalayın (örneğin, /Users/username/.local/bin/supabase-mcp-server).

2. Claude Desktop'ta MCP sunucusunu yapılandırın:

   • Claude Desktop'ı açın
   • Settings → Developer -> Edit Config MCP Servers'e gidin
   • Aşağıdaki JSON ile yeni bir yapılandırma ekleyin:

   {
     "mcpServers": {
       "supabase": {
         "command": "/full/path/to/supabase-mcp-server",  // Adım 1'den gerçek yolla değiştirin
         "env": {
           "QUERY_API_KEY": "your-api-key",  // Gerekli - API anahtarınızı thequery.dev adresinden alın
           "SUPABASE_PROJECT_REF": "your-project-ref",
           "SUPABASE_DB_PASSWORD": "your-db-password",
           "SUPABASE_REGION": "us-east-1",  // isteğe bağlı, varsayılan us-east-1
           "SUPABASE_ACCESS_TOKEN": "your-access-token",  // isteğe bağlı, management API için
           "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"  // isteğe bağlı, Auth Admin SDK için
         }
       }
     }
   }
   

⚠️ Önemli: Windsurf ve Cursor'dan farklı olarak Claude Desktop, yürütülebilire tam mutlak yol gerektirir. Yalnızca komut adını (supabase-mcp-server) kullanmak "spawn ENOENT" hatasına neden olur.

Yapılandırma doğruysa, Supabase MCP sunucusunun Claude Desktop'ta mevcut olarak listelendiğini göreceksiniz.

Cline

Cline ayrıca benzer JSON yapılandırması aracılığıyla MCP sunucularını destekler. Supabase MCP sunucusunu ayarlamak için bu adımları izleyin:

1. Yürütülebilire tam yol bulun (bu adım kritiktir):

   # macOS/Linux üzerinde
   which supabase-mcp-server
   
   # Windows üzerinde
   where supabase-mcp-server
   

   Döndürülen tam yolu kopyalayın (örneğin, /Users/username/.local/bin/supabase-mcp-server).

2. Cline'da MCP sunucusunu yapılandırın:

   • VS Code'da Cline'ı açın
   • Cline kenar çubuğundaki "MCP Servers" sekmesine tıklayın
   • "Configure MCP Servers" öğesine tıklayın
   • Bu cline_mcp_settings.json dosyasını açacaktır
   • Aşağıdaki yapılandırmayı ekleyin:

   {
     "mcpServers": {
       "supabase": {
         "command": "/full/path/to/supabase-mcp-server",  // Adım 1'den gerçek yolla değiştirin
         "env": {
           "QUERY_API_KEY": "your-api-key",  // Gerekli - API anahtarınızı thequery.dev adresinden alın
           "SUPABASE_PROJECT_REF": "your-project-ref",
           "SUPABASE_DB_PASSWORD": "your-db-password",
           "SUPABASE_REGION": "us-east-1",  // isteğe bağlı, varsayılan us-east-1
           "SUPABASE_ACCESS_TOKEN": "your-access-token",  // isteğe bağlı, management API için
           "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"  // isteğe bağlı, Auth Admin SDK için
         }
       }
     }
   }
   

Yapılandırma doğruysa, Cline MCP Servers listesinde Supabase MCP sunucusu yanında yeşil bir gösterge göreceksiniz ve panelin altında "supabase MCP server connected" onaylayan bir mesaj göreceksiniz.

Sorun Giderme

İşte size yardımcı olabilecek bazı ipuçları:

• Kurulumu hata ayıkla - terminalde supabase-mcp-server komutunu doğrudan çalıştırarak çalışıp çalışmadığını görmek. Çalışmazsa, kurulumda bir sorun olabilir.
• MCP Server yapılandırması - yukarıdaki adım çalışıyorsa, sunucu doğru şekilde kurulmuş ve yapılandırılmıştır. Doğru komutu sağladığınız sürece, IDE bağlanabiliyor olmalıdır. Sunucu yürütülebilirine doğru yolu sağlayın.
• "No tools found" hatası - Paket kurulmuş olmasına rağmen Cursor'da "Client closed - no tools available" görürseniz:
  • which supabase-mcp-server (macOS/Linux) veya where supabase-mcp-server (Windows) çalıştırarak yürütülebilire tam yolu bulun
  • MCP sunucu yapılandırmanızda yalnızca supabase-mcp-server yerine tam yolu kullanın
  • Örneğin: /Users/username/.local/bin/supabase-mcp-server veya C:\Users\username\.local\bin\supabase-mcp-server.exe
• Ortam değişkenleri - doğru veritabanına bağlanmak için env değişkenlerini mcp_config.json içinde veya global yapılandırma dizinine yerleştirilen .env dosyasında ayarladığınızdan emin olun (~/.config/supabase-mcp/.env macOS/Linux üzerinde veya %APPDATA%\supabase-mcp\.env Windows üzerinde).
• Günlüklere erişme - MCP sunucusu ayrıntılı günlükleri bir dosyaya yazar:
  • Günlük dosyası konumu:
    • macOS/Linux: ~/.local/share/supabase-mcp/mcp_server.log
    • Windows: %USERPROFILE%\.local\share\supabase-mcp\mcp_server.log
  • Günlükler bağlantı durumunu, yapılandırma ayrıntılarını ve işlem sonuçlarını içerir
  • Herhangi bir metin düzenleyici veya terminal komutları kullanarak günlükleri görüntüleyin:

    # macOS/Linux üzerinde
    cat ~/.local/share/supabase-mcp/mcp_server.log
    
    # Windows üzerinde (PowerShell)
    Get-Content "$env:USERPROFILE\.local\share\supabase-mcp\mcp_server.log"
    

Takılırsanız veya yukarıdaki talimatlardan herhangi biri yanlışsa, lütfen bir konu açın.

MCP Inspector

MCP sunucusu sorunlarını hata ayıklamaya yardımcı olacak süper faydalı bir araç MCP Inspector'dır. Kaynaktan yüklediyseniz, proje repo'sundan supabase-mcp-inspector komutunu çalıştırabilirsiniz ve inspector örneğini çalıştıracaktır. Günlükler ile birleştirildiğinde, sunucuda neler olup bittiğinin tam bir görünümünü alacaksınız.

📝 Paket olarak yüklediyseniz supabase-mcp-inspector çalıştırılması düzgün çalışmaz - yaklaşan sürümde doğrulayacağım ve düzelteceğim.

Özellik Özeti

Veritabanı sorgu araçları

v0.3+ sunucusu, yerleşik güvenlik kontrolleriyle kapsamlı veritabanı yönetimi yetenekleri sunar:

• SQL Sorgu Yürütme: Risk değerlendirmesiyle PostgreSQL sorgularını yürütün

  • Üç katmanlı güvenlik sistemi:
    • safe: Salt okunur işlemler (SELECT) - her zaman izin verilir
    • write: Veri değişiklikleri (INSERT, UPDATE, DELETE) - unsafe modu gerektirir
    • destructive: Şema değişiklikleri (DROP, CREATE) - unsafe modu + onay gerektirir

• SQL Ayrıştırma ve Doğrulama:

  • Doğru analiz için PostgreSQL parser'ını