xing5/mcp-google-sheets

---

🤔 Bu nedir?

mcp-google-sheets, herhangi bir MCP uyumlu istemci (Claude Desktop gibi) ile Google Sheets API arasında bir köprü görevi gören Python tabanlı bir MCP sunucusudur. Tanımlanmış bir araç seti kullanarak Google Elektronik Tablolarınızla etkileşim kurmanızı, yapay zeka tarafından yönlendirilen güçlü otomasyon ve veri manipülasyonu iş akışlarını etkinleştirmenizi sağlar.

---

🚀 Hızlı Başlangıç (uvx Kullanarak)

Sunucu temelde tek satırda çalışır: uvx mcp-google-sheets@latest.

Bu komut, en son kodu otomatik olarak indirecek ve çalıştıracaktır. Her zaman @latest kullanmanızı önerilir böylece en yeni sürümü en son özellikler ve hata düzeltmeleriyle elde edersiniz.

Aşağıda kullanılan kimlikler hakkında daha fazla bilgi için Kimlik Referans Kılavuzuna bakınız.

1. ☁️ Ön Koşul: Google Cloud Kurulumu

   • Google Cloud Platform kimlik bilgilerini yapılandırmanız ve gerekli API'leri etkinleştirmeniz gerekir. Çok güvenli bir şekilde Hizmet Hesabı kullanmanız şiddetle tavsiye edilir.
   • ➡️ Aşağıdaki Ayrıntılı Google Cloud Platform Kurulumu kılavuzuna geçin.

2. 🐍 uv Yükleyin

   • uvx, hızlı bir Python paket yükleyicisi ve çözücüsü olan uv'nin bir parçasıdır. Henüz yüklemediyseniz yükleyin:

     # macOS / Linux
     curl -LsSf https://astral.sh/uv/install.sh | sh
     # Windows
     powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
     # Veya pip kullanarak:
     # pip install uv
     

     Gerekirse uv öğesini PATH'inize eklemek için yükleyici çıktısındaki talimatları izleyin.

3. 🔑 Temel Ortam Değişkenlerini Ayarlayın (Hizmet Hesabı Önerilir)

   • Sunucuya nasıl kimlik doğrulaması yapacağını söylemeniz gerekir. Terminal'de şu değişkenleri ayarlayın:
   • (Linux/macOS)

     # Google Kurulum adımından alınan GERÇEK yol ve klasör kimliğiniz ile değiştirin
     export SERVICE_ACCOUNT_PATH="/path/to/your/service-account-key.json"
     export DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"
     

   • (Windows CMD)

     set SERVICE_ACCOUNT_PATH="C:\path\to\your\service-account-key.json"
     set DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"
     

   • (Windows PowerShell)

     $env:SERVICE_ACCOUNT_PATH = "C:\path\to\your\service-account-key.json"
     $env:DRIVE_FOLDER_ID = "YOUR_DRIVE_FOLDER_ID"
     

   • ➡️ Diğer seçenekler (OAuth, CREDENTIALS_CONFIG) için Ayrıntılı Kimlik Doğrulama & Ortam Değişkenleri bölümüne bakınız.

4. 🏃 Sunucuyu Çalıştırın!

   • uvx, mcp-google-sheets'in en son sürümünü otomatik olarak indirecek ve çalıştıracaktır:

     uvx mcp-google-sheets@latest
     

   • Sunucu başlayacak ve hazır olduğunu belirten günlükleri yazdıracaktır.

   • 💡 Pro İpucu: En yeni sürümü hata düzeltmeleri ve özelliklerle aldığınızdan emin olmak için her zaman @latest kullanın. @latest olmadan, uvx önbelleğe alınmış eski bir sürümü kullanabilir.

5. 🔌 MCP İstemcinizi Bağlayın

   • İstemcinizi (ör. Claude Desktop) çalışan sunucuya bağlanacak şekilde yapılandırın.
   • Kullandığınız istemciye bağlı olarak, istemci sunucuyu sizin için başlatabileceğinden 4. adıma ihtiyaç duymayabilirsiniz. Ancak her şeyin düzgün ayarlandığından emin olmak için 4. adımı test etmek iyi bir uygulamadır.
   • ➡️ Örnekler için Claude Desktop ile Kullanım bölümüne bakınız.

6. ⚡ İsteğe Bağlı: Araç Filtrelemesini Etkinleştirin (Bağlam Kullanımını Azaltın)

   • Varsayılan olarak, tüm 19 araç etkindir (~13K token). Bağlam kullanımını azaltmak için yalnızca ihtiyacınız olan araçları etkinleştirin.
   • ➡️ Ayrıntılar için Araç Filtreleme bölümüne bakınız.

Hazırsınız! MCP istemciniz aracılığıyla komut vermeye başlayın.

---

✨ Temel Özellikler

• Sorunsuz Entegrasyon: Doğrudan Google Drive & Google Sheets API'lerine bağlanır.
• Kapsamlı Araçlar: Geniş bir işlem yelpazesi sunar (CRUD, listeleme, toplu işlem, paylaşma, biçimlendirme vb.).
• Esnek Kimlik Doğrulama: Hizmet Hesaplarını (önerilir), OAuth 2.0'ı ve ortam değişkenleri aracılığıyla doğrudan kimlik bilgilerini destekler.
• Kolay Dağıtım: uvx ile anında çalıştırın (sıfır kurulum hissi) veya geliştirme için uv kullanarak klonlayın.
• Yapay Zeka İçin Hazır: MCP uyumlu istemcilerle kullanım için tasarlanmış, doğal dil elektronik tablo etkileşimini sağlar.
• Araç Filtreleme: --include-tools veya ENABLED_TOOLS ortam değişkeni ile yalnızca ihtiyacınız olan araçları etkinleştirerek bağlam penceresi kullanımını azaltın.

---

🎯 Araç Filtreleme (Bağlam Kullanımını Azaltın)

Sorun: Varsayılan olarak, bu MCP sunucusu tüm 19 aracı ortaya koymakta, herhangi bir konuşmaya başlamadan önce ~13.000 token tüketmektedir. Yalnızca birkaç aracı ihtiyacınız varsa, bu değerli bağlam penceresi alanını boşa harcar.

Çözüm: Yalnızca gerçekten kullandığınız araçları etkinleştirmek için araç filtrelemesini kullanın.

Araç Filtrelemesini Nasıl Etkinleştireceğiniz

Araçları şu seçeneklerden biriyle filtreleyebilirsiniz:

1. Komut satırı argümanı --include-tools:

   {
     "mcpServers": {
       "google-sheets": {
         "command": "uvx",
         "args": [
           "mcp-google-sheets@latest",
           "--include-tools",
           "get_sheet_data,update_cells,list_spreadsheets,list_sheets"
         ],
         "env": {
           "SERVICE_ACCOUNT_PATH": "/path/to/credentials.json"
         }
       }
     }
   }
   

2. Ortam değişkeni ENABLED_TOOLS:

   {
     "mcpServers": {
       "google-sheets": {
         "command": "uvx",
         "args": ["mcp-google-sheets@latest"],
         "env": {
           "SERVICE_ACCOUNT_PATH": "/path/to/credentials.json",
           "ENABLED_TOOLS": "get_sheet_data,update_cells,list_spreadsheets,list_sheets"
         }
       }
     }
   }
   

Kullanılabilir Araç Adları

Filtreleme sırasında, bu tam araç adlarını kullanın (virgülle ayrılmış, boşluksuz):

En Yaygın Araçlar (önerilen alt küme):

• get_sheet_data - Elektronik tablolardan oku
• update_cells - Elektronik tablolara yaz
• list_spreadsheets - Elektronik tabloları bul
• list_sheets - Sekmelerde gezin

Tüm Kullanılabilir Araçlar:

• add_columns
• add_rows
• batch_update
• batch_update_cells
• copy_sheet
• create_sheet
• create_spreadsheet
• find_in_spreadsheet
• get_multiple_sheet_data
• get_multiple_spreadsheet_summary
• get_sheet_data
• get_sheet_formulas
• list_folders
• list_sheets
• list_spreadsheets
• rename_sheet
• search_spreadsheets
• share_spreadsheet
• update_cells

Not: --include-tools veya ENABLED_TOOLS belirtilmezse, tüm araçlar etkindir (varsayılan davranış).

---

🛠️ Kullanılabilir Araçlar & Kaynaklar

Bu sunucu, Google Sheets ile etkileşim kurmak için aşağıdaki araçları ortaya koymaktadır:

Aşağıda kullanılan kimlikler hakkında daha fazla bilgi için Kimlik Referans Kılavuzuna bakınız.

(Giriş parametreleri aksi belirtilmedikçe genellikle dizelerdir)

• list_spreadsheets: Yapılandırılmış Drive klasöründeki (Hizmet Hesabı) veya kullanıcı tarafından erişilebilen (OAuth) elektronik tabloları listeler.
  • folder_id (isteğe bağlı dize): Aramada kullanılacak Google Drive klasör kimliği. URL'sinden alın. Belirtilmezse, yapılandırılmış varsayılan klasörü veya 'My Drive'ı arar.
  • Döndürür: Nesne listesi [{id: string, title: string}]
• create_spreadsheet: Yeni bir elektronik tablo oluşturur.
  • title (dize): Elektronik tablo için istenen başlık. Örnek: "Quarterly Report Q4".
  • folder_id (isteğe bağlı dize): Elektronik tablonun oluşturulması gereken Google Drive klasör kimliği. URL'sinden alın. Belirtilmezse, yapılandırılan varsayılanı veya kökü kullanır.
  • Döndürür: spreadsheetId, title ve folder içeren elektronik tablo bilgisi nesnesi.
• get_sheet_data: Bir sayfadaki/sekmedeki bir aralıktan veri okur.
  • spreadsheet_id (dize): Elektronik tablo kimliği (URL'sinden).
  • sheet (dize): Sayfanın/sekmenin adı (ör. "Sheet1").
  • range (isteğe bağlı dize): A1 gösterimi (ör. 'A1:C10', 'Sheet1!B2:D'). Belirtilmezse, sheet tarafından belirtilen tüm sayfayı/sekmeyi okur.
  • include_grid_data (isteğe bağlı boole, varsayılan False): True ise, biçimlendirme ve meta veriler dahil tam ızgara verileri döndürür (çok daha büyük). False ise, yalnızca değerleri döndürür (daha verimli).
  • Döndürür: include_grid_data=True ise, meta verili tam ızgara verileri (get yanıtı). False ise, Values API'sinden bir değerler sonucu nesnesi (values.get yanıtı).
• get_sheet_formulas: Bir sayfadaki/sekmedeki bir aralıktan formülleri okur.
  • spreadsheet_id (dize): Elektronik tablo kimliği (URL'sinden).
  • sheet (dize): Sayfanın/sekmenin adı (ör. "Sheet1").
  • range (isteğe bağlı dize): A1 gösterimi (ör. 'A1:C10', 'Sheet1!B2:D'). Belirtilmezse, sheet tarafından belirtilen sayfadaki/sekmedeki tüm formülleri okur.
  • Döndürür: Hücre formülleri 2D dizisi (dizilerin dizisi) (values.get yanıtı).
• update_cells: Belirli bir aralığa veri yazar. Mevcut verilerin üzerine yazar.
  • spreadsheet_id (dize): Elektronik tablo kimliği (URL'sinden).
  • sheet (dize): Sayfanın/sekmenin adı (ör. "Sheet1").
  • range (dize): Yazılacak A1 gösterimi aralığı (ör. 'A1:C3').
  • data (dizilerin dizisi): Yazılacak değerlerin 2D dizisi. Örnek: [[1, 2, 3], ["a", "b", "c"]].
  • Döndürür: Güncelleme sonucu nesnesi (values.update yanıtı).
• batch_update_cells: Tek bir API çağrısında birden çok aralığı günceller.
  • spreadsheet_id (dize): Elektronik tablo kimliği (URL'sinden).
  • sheet (dize): Sayfanın/sekmenin adı (ör. "Sheet1").
  • ranges (nesne): Aralık dizelerini (A1 gösterimi) değerlerin 2D dizilerine eşleyen sözlük. Örnek: { "A1:B2": [[1, 2], [3, 4]], "D5": [["Hello"]] }.
  • Döndürür: İşlemin sonucu (values.batchUpdate yanıtı).
• add_rows: Belirtilen dizine bir sayfaya/sekmeye boş satırlar ekler (ekler).
  • spreadsheet_id (dize): Elektronik tablo kimliği (URL'sinden).
  • sheet (dize): Sayfanın/sekmenin adı (ör. "Sheet1").
  • count (tam sayı): Eklenecek boş satır sayısı.
  • start_row (isteğe bağlı tam sayı, varsayılan 0): Satırları eklemeye başlamak için 0 tabanlı satır dizini. Belirtilmezse, varsayılan olarak 0 (başın başına eklenir).
  • Döndürür: İşlemin sonucu (batchUpdate yanıtı).
• list_sheets: Elektronik tablo içinde tüm sayfa/sekme adlarını listeler.
  • spreadsheet_id (dize): Elektronik tablo kimliği (URL'sinden).
  • Döndürür: Sayfa/sekme adı dizelerinin listesi. Örnek: ["Sheet1", "Sheet2"].
• create_sheet: Elektronik tabloya yeni bir sayfa/sekme ekler.
  • spreadsheet_id (dize): Elektronik tablo kimliği (URL'sinden).
  • title (dize): Yeni sayfa/sekme adı.
  • Döndürür: Yeni sayfa özellikleri nesnesi.
• get_multiple_sheet_data: Tek bir çağrıda potansiyel olarak farklı elektronik tablolardaki birden çok aralıktan veri alır.
  • queries (nesne dizisi): Her nesne spreadsheet_id, sheet ve range'ı gerektirir. Örnek: [{"spreadsheet_id": "abc", "sheet": "Sheet1", "range": "A1:B2"}, ...].
  • Döndürür: Her biri sorgu parametrelerini ve alınan data'ı veya bir error'ı içeren nesne listesi. Her data, bir values.get yanıtı.
• get_multiple_spreadsheet_summary: Birden çok elektronik tablo için başlıkları, sayfa/sekme adlarını, başlıkları ve ilk birkaç satırı alır.
  • spreadsheet_ids (dize dizisi): Elektronik tabloların kimliği (URL'lerinden).
  • rows_to_fetch (isteğe bağlı tam sayı, varsayılan 5): Kaç satır (başlık dahil) önizlenecek. Örnek: 5.
  • Döndürür: Her elektronik tablo için özet nesnelerinin listesi.
• share_spreadsheet: Elektronik tabloyu belirtilen kullanıcılar/e-postalar ve rollerle paylaşır.
  • spreadsheet_id (dize): Elektronik tablo kimliği (URL'sinden).
  • recipients (nesne dizisi): [{"email_address": "user@example.com", "role": "writer"}, ...]. Roller: reader, commenter, writer.
  • send_notification (isteğe bağlı boole, varsayılan True): Alıcılara e-posta bildirimleri gönder.
  • Döndürür: successes ve failures listelerini içeren sözlük.
• add_columns: Belirtilen dizine bir sayfaya/sekmeye boş sütunlar ekler (ekler).
  • spreadsheet_id (dize): Elektronik tablo kimliği (URL'sinden).
  • sheet (dize): Sayfanın/sekmenin adı (ör. "Sheet1").
  • count (tam sayı): Eklenecek boş sütun sayısı.
  • start_column (isteğe bağlı tam sayı, varsayılan 0): Eklemeye başlamak için 0 tabanlı sütun dizini. Belirtilmezse, varsayılan olarak 0 (başın başına eklenir).
  • Döndürür: İşlemin sonucu (batchUpdate yanıtı).
• copy_sheet: Bir sayfayı/sekmeyi bir elektronik tablodan diğerine çoğaltır ve isteğe bağlı olarak yeniden adlandırır.
  • src_spreadsheet (dize): Kaynak elektronik tablo kimliği (URL'sinden).
  • src_sheet (dize): Kaynak sayfanın/sekmenin adı (ör. "Sheet1").
  • dst_spreadsheet (dize): Hedef elektronik tablo kimliği (URL'sinden).
  • dst_sheet (dize): Hedef elektronik tablodaki istenen sayfa/sekme adı.
  • Döndürür: Kopyalama ve isteğe bağlı yeniden adlandırma işlemlerinin sonucu.
• rename_sheet: Mevcut bir sayfayı/sekmeyi yeniden adlandırır.
  • spreadsheet (dize): Elektronik tablo kimliği (URL'sinden).
  • sheet (dize): Geçerli sayfa/sekme adı (ör. "Sheet1").
  • new_name (dize): Yeni sayfa/sekme adı (ör. "Transactions").
  • Döndürür: İşlemin sonucu (batchUpdate yanıtı).
• add_chart: Google Elektronik Tablasında belirtilen verilerden bir grafik oluşturur.
  • spreadsheet_id (dize): Elektronik tablo kimliği (URL'sinden).
  • sheet (dize): Verileri içeren sayfanın/sekmenin adı (ör. "Sheet1").
  • chart_type (dize): Oluşturulacak grafik türü. Seçenekler: COLUMN (dikey çubuklar), BAR (yatay çubuklar), LINE, AREA, PIE, SCATTER, COMBO, HISTOGRAM.
  • data_range (dize): Grafik verileri için A1 gösterimi aralığı (ör. "A1:C10"). İlk satır başlık olarak kabul edilir.
  • title (isteğe bağlı dize): Grafik başlığı.
  • x_axis_label (isteğe bağlı dize): X ekseni etiketi (alt eksen). Pasta grafikleri için uygulanamaz.
  • y_axis_label (isteğe bağlı dize): Y ekseni etiketi (sol eksen). Pasta grafikleri için uygulanamaz.
  • position_x (isteğe bağlı tam sayı, varsayılan 0): Sol üst köşeden piksel cinsinden yatay konum ofseti.
  • position_y (isteğe bağlı tam sayı, varsayılan 0): Sol üst köşeden piksel cinsinden dikey konum ofseti.
  • width (isteğe bağlı tam sayı, varsayılan 600): Grafiğin piksel cinsinden genişliği.
  • height (isteğe bağlı tam sayı, varsayılan 400): Grafiğin piksel cinsinden yüksekliği.
  • Döndürür: Başarı durumu, grafik kimliği ve işlem ayrıntılarını içeren sonuç nesnesi.

MCP Kaynakları:

• spreadsheet://{spreadsheet_id}/info: Google Elektronik Tablosu hakkında temel meta verileri alın.
  • Döndürür: Elektronik tablo bilgisine sahip JSON dizesi.

---

☁️ Google Cloud Platform Kurulumu (Ayrıntılı)

Bu kurulum sunucuyu çalıştırmadan önce gereklidir.

1. GCP Projesi Oluşturun/Seçin: Google Cloud Konsolu'na gidin.
2. API'leri Etkinleştirin: "APIs & Services" -> "Library" sekmesine gidin. Ara ve etkinleştirin:
   • Google Sheets API
   • Google Drive API
3. Kimlik Bilgilerini Yapılandırın: Aşağıda bir kimlik doğrulama yöntemi seçmeniz gerekir (Hizmet Hesabı önerilir).

---

🔑 Kimlik Doğrulama & Ortam Değişkenleri (Ayrıntılı)

Sunucu, Google API'lerine erişmek için kimlik bilgilerine ihtiyaç duyar. Bir yöntem seçin:

Aşağıda kullanılan kimlikler hakkında daha fazla bilgi için Kimlik Referans Kılavuzuna bakınız.

Yöntem A: Hizmet Hesabı (Sunucular/Otomasyon İçin Önerilir) ✅

• Neden? Başsız (tarayıcı gerekmez), güvenli, sunucu ortamları için idealdir. Kolayca süresi dolmaz.
• Adımlar:
  1. Hizmet Hesabı Oluşturun: GCP Konsolu -> "IAM & Admin" -> "Service Accounts" sekmesinde.
     • "+ CREATE SERVICE ACCOUNT" öğesine tıklayın. Adlandırın (örn. mcp-sheets-service).
     • Rolleri Verin: Geniş erişim için Editor rolünü ekleyin veya daha dar izinler için (ör. roles/drive.file ve belirli Sheets rolleri) daha ayrıntılı roller ekleyin.
     • "Done" öğesine tıklayın. Hesabı bulun, Actions (⋮) -> "Manage keys" öğesine tıklayın.
     • "ADD KEY" -> "Create new key" -> JSON -> "CREATE" öğesine tıklayın.
     • JSON anahtar dosyasını indirin ve güvenle saklayın.
  2. Google Drive Klasörü Oluşturun & Paylaşın:
     • Google Drive sekmesinde bir klasör oluşturun (örn. "AI Managed Sheets").
     • URL'den Klasör Kimliğini not edin: `https://drive.google.com/drive/folders/THIS