Google Analytics MCP sunucusunu deneyin

Google Analytics Model Context Protocol (MCP) sunucusu, Google Analytics verilerinizi büyük dil modellerine (LLM'ler) ve Gemini gibi yapay zeka ajanlarına bağlamanıza olanak tanır. Raporları doğal dilde sorgulamak, mülk yapılandırmalarını incelemek ve özel analiz temsilcileri oluşturmak için MCP sunucusunu kullanabilirsiniz.

MCP sunucusunu ayarlama GitHub'da görüntüleyin Kurulum eğitimini izleyin

Ön koşullar

Google Analytics MCP sunucusunu yapılandırmadan önce aşağıdaki koşulları karşılamanız gerekir:

  1. Python'u ve bir paket çalıştırıcıyı yükleyin:

  2. Google Analytics API'lerini şurada etkinleştirin :

    • Bir proje oluşturun veya seçin.

    • Projenizde hem Google Analytics Admin API'yi (analyticsadmin.googleapis.com) hem de Google Analytics Data API'yi (analyticsdata.googleapis.com) etkinleştirin:

      gcloud services enable analyticsadmin.googleapis.com \
  analyticsdata.googleapis.com \
  --project=YOUR_PROJECT_ID

  3. Google Analytics mülküne erişim izni verme:

Kimlik doğrulamayı ayarlama

Google Analytics MCP sunucusu, salt okunur Google Analytics OAuth 2.0 kapsamıyla Uygulama Varsayılan Kimlik Bilgileri'ni (ADC) kullanarak kimlik doğrulaması yapar:

https://www.googleapis.com/auth/analytics.readonly

ADC'yi Google kullanıcı hesabınızı veya bir hizmet hesabını kullanarak yapılandırabilirsiniz.

1. seçenek: Kullanıcı kimlik bilgileriyle kimlik doğrulama

  1. gcloud CLI'yı yükleyin ve ilk kullanıma hazırlayın.

  2. Gerekli kapsamlarla gcloud auth application-default login komutunu çalıştırın:

    gcloud auth application-default login \
  --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform"

    İndirilen bir OAuth 2.0 masaüstü veya web istemcisi yapılandırma dosyası kullanıyorsanız (OAuth istemcilerini yönetme bölümüne bakın) --client-id-file değerini iletin:

    gcloud auth application-default login \
  --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform" \
  --client-id-file=YOUR_CLIENT_JSON_FILE

  3. Komut tamamlandığında konsola yazdırılan kimlik bilgileri yolunu (Credentials saved to file: [PATH_TO_CREDENTIALS_JSON]) kopyalayın. MCP istemcinizi yapılandırırken GOOGLE_APPLICATION_CREDENTIALS içinde bu yolu kullanırsınız.

2. seçenek: Hizmet hesabıyla kimlik doğrulama

Google Analytics mülkünüze Görüntüleyen erişimi olan bir hizmet hesabıyla kimlik doğrulaması yapmak için:

  • Hizmet hesabı JSON anahtar dosyası: MCP istemci yapılandırmanızda GOOGLE_APPLICATION_CREDENTIALS değerini hizmet hesabı JSON dosyanızın mutlak yoluna ayarlayın.

  • Hizmet hesabı kimliğine bürünme: gcloud CLI ile hizmet hesabı kimliğine bürünerek ADC kimlik bilgilerini oluşturun:

    gcloud auth application-default login \
  --impersonate-service-account=SERVICE_ACCOUNT_EMAIL \
  --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform"

MCP istemcinizi yapılandırma

Sunucu, PyPI'da analytics-mcp olarak yayınlanır ve hem analytics-mcp hem de google-analytics-mcp konsol komut dosyalarını gösterir.

Aşağıdaki yapılandırmalarda şunları değiştirin:

  • PATH_TO_CREDENTIALS_JSON yerine ADC veya hizmet hesabı JSON dosyanızın mutlak yolunu yazın.
  • YOUR_PROJECT_ID ifadesini, Google Analytics API'lerini etkinleştirdiğiniz proje kimliğiyle değiştirin.

Antigravity CLI ve Antigravity IDE

  1. Antigravity CLI veya Antigravity IDE'yi yükleyin.

  2. analytics-mcp sunucusunu ~/.gemini/config/mcp_config.json'e (veya çalışma alanınızdaki .agents/mcp_config.json'e) ekleyin:

    {
  "mcpServers": {
    "analytics-mcp": {
      "command": "pipx",
      "args": ["run", "analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

  3. analytics-mcp cihazının bağlı olduğunu doğrulayın:

    • Antigravity CLI: agy komutunu çalıştırın, ardından yapılandırılmış MCP sunucularınızı görüntülemek için /mcp yazın.
    • Antigravity IDE: Ayarlar > Özelleştirmeler > Yüklü MCP Sunucuları'nı açıp Yenile'yi tıklayın.

Claude Desktop ve Claude Code

Claude Desktop için sunucuyu claude_desktop_config.json dosyanıza ekleyin (macOS'te ~/Library/Application Support/Claude/claude_desktop_config.json veya Windows'ta %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "analytics-mcp": {
      "command": "pipx",
      "args": ["run", "analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

Claude Code için komut satırı aracını kullanarak sunucuyu kaydedin:

claude mcp add analytics-mcp \
  --scope user \
  -e GOOGLE_APPLICATION_CREDENTIALS="PATH_TO_CREDENTIALS_JSON" \
  -e GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" \
  -- pipx run analytics-mcp

İmleç

Sunucuyu proje dizininizdeki .cursor/mcp.json dosyasına (veya genel yapılandırma için ~/.cursor/mcp.json dosyasına) ekleyin. google-analytics-mcp komutunu uvx veya pipx kullanarak çağırabilirsiniz:

{
  "mcpServers": {
    "google-analytics-mcp": {
      "command": "uvx",
      "args": ["--from", "analytics-mcp", "google-analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

uvx kullanarak en son geliştirme sürümünü doğrudan GitHub'dan çalıştırmak için "args" dosyasını güncelleyin:

"args": [
  "--from",
  "git+https://github.com/googleanalytics/google-analytics-mcp.git",
  "google-analytics-mcp"
]

Alternatif olarak, pipx kullanmak için "command" değerini "pipx" olarak değiştirin ve "args" değerini şu şekilde ayarlayın:

"command": "pipx",
"args": [
  "run",
  "--spec",
  "git+https://github.com/googleanalytics/google-analytics-mcp.git",
  "google-analytics-mcp"
]

Kullanılabilir MCP araçları

Google Analytics MCP sunucusu, MCP istemcinize salt okunur araçlar sunmak için Admin API ve Data API v1'i kullanır:

  • Hesap ve mülk keşfi (Admin API):
    • get_account_summaries: Kimliği doğrulanmış kullanıcının erişebileceği Google Analytics hesaplarını ve mülklerini listeler (accountSummaries.list).
    • get_property_details: Belirli bir Google Analytics mülkü (properties.get) için yapılandırma ayrıntılarını döndürür.
    • list_google_ads_links: Bir mülkün (properties.googleAdsLinks.list) Google Ads hesaplarıyla olan bağlantılarını listeler.
    • list_property_annotations: Bir mülk için yapılandırılmış notları listeler (properties.reportingDataAnnotations.list).
  • Raporlama ve şema denetimi (Data API v1):
    • get_custom_dimensions_and_metrics: Bir mülk için tanımlanan özel boyutları ve özel metrikleri alır (getMetadata).
    • run_report: Standart bir Google Analytics raporu çalıştırır (runReport).
    • run_realtime_report: Bir Google Analytics anlık raporu çalıştırır (runRealtimeReport).
    • run_funnel_report: Google Analytics dönüşüm hunisi keşfi raporu çalıştırır (runFunnelReport).
    • run_conversions_report: Dönüşüm performansı raporu (runConversionsReport) çalıştırır.

Örnek istemler

Bağlantı kurulduktan sonra yapay zeka asistanınıza aşağıdaki gibi sorular sorabilirsiniz:

  • Dün kaç kullanıcım oldu?
  • Dün en çok satan ürünlerim hangileriydi?
  • Aylık 5.000 ABD doları tutarında bir pazarlama bütçem var ve daha fazla gelir elde etmem gerekiyor. Veriye dayalı bir pazarlama planı oluşturmama yardım et.
  • Mülkümde hangi özel boyutlar ve özel metrikler yapılandırılmış?
  • Son 90 gün içinde Google Analytics mülkümdeki en popüler etkinlikler hangileri?

Sorun giderme

Sık karşılaşılan kurulum ve çalışma zamanı hatalarını çözmek için aşağıdaki kontrol listesini kullanın:

  • 403 PERMISSION_DENIED (API etkinleştirilmemiş veya mülk izinleri yetersiz):
    • GOOGLE_CLOUD_PROJECT tarafından belirtilen projesinde hem Google Analytics Admin API'nin (analyticsadmin.googleapis.com) hem de Google Analytics Data API'nin (analyticsdata.googleapis.com) etkinleştirildiğini onaylayın.
    • Kimlik doğrulama işlemini gerçekleştiren kullanıcı veya hizmet hesabının, Google Analytics kullanıcı arayüzünde hedef Google Analytics mülkünde en az Görüntüleyen rolüne (roles/analytics.viewer) sahip olduğunu doğrulayın.
    • Hata mesajında Request had insufficient authentication scopes ifadesi yer alıyorsa gcloud auth application-default login komutunu https://www.googleapis.com/auth/analytics.readonly ve https://www.googleapis.com/auth/cloud-platform kapsamlarıyla yeniden çalıştırın.

  • Kota projesi (GOOGLE_CLOUD_PROJECT) eksik veya 403 ACCESS_NOT_CONFIGURED:

    • Kullanıcı ADC kimlik bilgileriyle kimliği doğrulanmış istekler için Google Analytics API'lerinin etkinleştirildiği bir kota projesi gerekir. MCP sunucunuzun env yapılandırmasında "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID" değerini ayarlayın veya ADC dosyanızda kota projesini ayarlayın:

      gcloud auth application-default set-quota-project YOUR_PROJECT_ID

  • 401 UNAUTHENTICATED veya kimlik bilgileri dosyası bulunamadı:

    • GOOGLE_APPLICATION_CREDENTIALS için mutlak yol kullanın (ör. /Users/username/.config/gcloud/application_default_credentials.json). ~ veya $HOME değişkenlerini kullanmaktan kaçının. Birçok MCP ana makinesi, JSON yapılandırma dosyalarındaki kabuk değişkenlerini genişletmez.
    • Kullanıcı kimlik bilgilerinizin süresi dolduysa gcloud auth application-default login komutunu yeniden çalıştırın.

  • Sunucu başlatılamıyor (spawn pipx ENOENT, uvx: command not found veya Python sürüm hataları):

    • Python 3.10 veya sonraki bir sürümün yüklü olduğunu doğrulayın (python3 --version).
    • Masaüstü GUI uygulamaları (Claude Desktop ve Cursor gibi) genellikle etkileşimli kabuğunuzu PATH devralmaz. "command" içindeki "pipx" veya "uvx" değerini, which pipx ya da which uvx tarafından döndürülen mutlak ikili program yoluyla (ör. /opt/homebrew/bin/pipx veya /Users/username/.local/bin/pipx) değiştirin.