Yapay zekâ ajanlarını listingsAPI MCP'ye bağlayın

Claude, ChatGPT, Cursor veya Gemini'yi barındırılan MCP sunucusuna bağlayın; konum, işletme kaydı ve yorumlarınızı sizinle aynı araçlarla okuyup işlesin.

Listings API, https://listingsapi.com/mcp adresinde bir Model Context Protocol (MCP) sunucusu barındırır. Yüklemeniz veya çalıştırmanız gereken bir şey yoktur. MCP destekleyen bir yapay zekâ asistanı bu URL'ye bağlanır, her REST uç noktası için bir araç ve birkaç dokümantasyon aracı bulur ve bunları hesabınızda çağırır. Bu kılavuz, yaygın kullanılan istemcilerin her birini bağlama ve ardından bağlantıyı doğrulama adımlarını açıklar.

1. Ajanın hangi araçlara erişebildiğini öğrenin

Sunucu, yaklaşık üçte ikisi salt okunur olan 60'tan biraz fazla araç sunar. Araç adları REST kaynaklarıyla eşleşir; dolayısıyla locations_search, listings_premium, reviews_respond ve posts_create_social, karşılık gelen uç noktalarla aynı işlemleri, aynı parametreler ve aynı yanıt yapısıyla gerçekleştirir. Üç dokümantasyon aracı olan search_docs, get_doc ve get_endpoint, asistanın istek gövdesinin yapısını tahmin etmek yerine bir sayfaya veya uç noktanın sözleşmesine bakmasını sağlar.

Araç grubuÖrneklerGereken yetki
Konumlarlocations_all, locations_search, locations_create, locations_updateSorgulama için Read, oluşturma ve güncelleme için Write
İşletme kayıtlarılistings_premium, listings_duplicates, listings_mark_duplicateRead, yinelenen kayıtları işaretlemek için Write
Bağlı hesaplarconnected_accounts_list, connected_accounts_listings, connected_accounts_connect_listingRead, bağlama ve içe aktarma için Write
Yorumlarreviews_list, reviews_get, reviews_respond, reviews_analyticsRead, yanıtlar için Write
Gönderilerposts_social_post_view, posts_create_socialRead, yayımlama için Write
Analizleranalytics_google, analytics_facebook, analytics_bing (kullanımdan kaldırılmıştır, veri döndürmez)Read
Hesapwhoami, get_usage, get_subscription, recent_errorsRead
Dokümantasyonsearch_docs, get_doc, get_endpoint, list_endpointsYok

Gönderi silme veya konum arşivleme gibi yıkıcı işlemler araç olarak sunulmaz. Bu işlemler için REST API'yi veya bir SDK'yı kullanın; böylece asistan kendi başına veri kaldıramaz.

2. İstemcinin nasıl oturum açacağını seçin

Her istemci, iki yöntemden biriyle kimlik doğrular. Her iki yöntem de sunucu tarafında aynı API anahtarını kullanır; bu nedenle istek hızı sınırları ve kullanım raporlaması aynıdır.

YöntemYapıştıracağınız içerikEn uygun olduğu durumlar
API anahtarı üst bilgisiSabit bir üst bilgi olarak Authorization: API <your key>Yapılandırma dosyasını sizin yönettiğiniz CLI'lar ve düzenleyiciler
OAuth 2.0Hiçbir şey. İstemci bir tarayıcı açar, siz oturum açar ve read veya read write kapsamını onaylarsınızClaude ve ChatGPT gibi barındırılan asistanlar veya anahtarın kendisini elinde bulundurmaması gereken herkes

OAuth, PKCE ile yetkilendirme kodu akışını ve dinamik istemci kaydını kullanır; bu nedenle istemcinin önceden verilmiş kimlik bilgilerine ihtiyacı yoktur. Meta veriler https://listingsapi.com/.well-known/oauth-authorization-server adresindedir. Kapsamlar read ve write şeklindedir; kapsam istemeyen bir istemciye read verilir. Her onay, ilgili bağlantıya özel bir anahtar oluşturur ve bu anahtarı diğer anahtarlar gibi /dashboard/keys üzerinden iptal edebilirsiniz.

3. Claude'u bağlayın

Claude.ai ve Claude Desktop. Sunucu bağlayıcı dizininde listelendiği için en hızlı yol, https://claude.ai/directory/listings-api adresini açıp Connect (Bağlan) düğmesine tıklamaktır. Claude OAuth akışını yürütür, siz kapsamları onaylarsınız ve + düğmesinin ardından Connectors (Bağlayıcılar) seçeneğini kullanarak bağlayıcıyı etkinleştirdiğiniz her sohbette araçlar kullanılabilir.

URL ile eklemeyi tercih ederseniz Customize (Özelleştir), ardından Connectors (Bağlayıcılar) bölümüne gidin, + ve Add custom connector (Özel bağlayıcı ekle) seçeneklerine tıklayın, https://listingsapi.com/mcp adresini yapıştırın ve Add (Ekle) düğmesine tıklayın. Advanced settings (Gelişmiş ayarlar) alanını boş bırakın; sunucu Claude'u otomatik olarak istemci olarak kaydeder. Team ve Enterprise planlarında bir hesap sahibi, Organization settings (Kuruluş ayarları) altındaki Connectors (Bağlayıcılar) bölümünden bağlayıcıyı ekler, ardından üyeler bu bağlayıcının Connect (Bağlan) düğmesine tıklar. Claude, sizin makinenizden değil Anthropic'in sunucularından bağlanır; barındırılan URL'nin önemli olmasının nedeni budur.

Claude Code. Tek bir komut, anahtarınızla sunucuyu ekler:

Claude Code
claude mcp add --transport http listingsapi https://listingsapi.com/mcp \--header "Authorization: API $LISTINGSAPI_KEY"

Bunun yerine tarayıcı üzerinden oturum açmak için --header bayrağını kaldırın ve Claude Code içinde /mcp komutunu çalıştırın. Sunucu yapılandırmasını tüm ekibin paylaştığı bir .mcp.json dosyasına ekleyip sürüm kontrolüne kaydetmek için --scope project kullanın; beraberinde bir anahtarı sürüm kontrolüne kaydetmeyin.

4. ChatGPT'yi bağlayın

ChatGPT, Developer mode (Geliştirici modu) açıldığında uzak MCP sunucularına özel bağlayıcı olarak bağlanır. Bu özellik Plus, Pro, Business, Enterprise ve Edu planlarında kullanılabilir; ücretsiz planda kullanılamaz.

  1. Profil menünüzden Settings (Ayarlar) bölümünü açın ve Developer mode (Geliştirici modu) seçeneğini etkinleştirin. Kullandığınız sürüme bağlı olarak bu seçenek Apps & Connectors (Uygulamalar ve bağlayıcılar) veya Security and login (Güvenlik ve oturum açma) altında bulunur.
  2. Bağlayıcılar sayfasında (güncel sürümlerde Plugins (Eklentiler) olarak adlandırılır) + veya Create (Oluştur) düğmesine tıklayın.
  3. Bir ad girin, sunucu URL'si olarak https://listingsapi.com/mcp adresini yapıştırın ve kimlik doğrulama için OAuth seçeneğini belirleyin. Kaydedin.
  4. ChatGPT oturum açma sayfasını açar. read veya read write seçeneğini onaylayın.
  5. Yeni bir sohbette araçlar menüsünü açın, bağlayıcıyı seçin ve araçlarıyla birlikte göründüğünü doğrulayın. Yazma araçları için bir ajan talimatıyla onay istenmeye devam edilir.

Codex CLI. OpenAI'ın terminal ajanı, MCP sunucularını ~/.codex/config.toml dosyasından okur. Codex, HTTP sunucuları için OAuth sürecini kendisi başlatır ve sunucunun bildirdiği kapsamları dikkate alır; bu nedenle üstbilgi satırı isteğe bağlıdır:

~/.codex/config.toml
[mcp_servers.listingsapi]url = "https://listingsapi.com/mcp"http_headers = { "Authorization" = "API <your key>" }

5. Cursor'ı bağlayın

/dashboard/mcp adresindeki kontrol paneli sayfasında bir Add to Cursor (Cursor'a ekle) düğmesi bulunur. Bu düğme, sunucu URL'si ve anahtarınız önceden doldurulmuş bir Cursor kurulum bağlantısını açar; böylece tek tıklamayla kurulum tamamlanır.

Elle yapılandırmak için sunucuyu tüm projelerde kullanılmak üzere ~/.cursor/mcp.json dosyasına veya tek bir depo içindeki .cursor/mcp.json dosyasına ekleyin:

~/.cursor/mcp.json
{"mcpServers": {  "listingsapi": {    "url": "https://listingsapi.com/mcp",    "headers": {      "Authorization": "API <your key>"    }  }}}

Bunun yerine OAuth ile oturum açmak için headers bloğunu kaldırın: Cursor, Settings (Ayarlar) altında MCP bölümündeki sunucu kaydında bir Connect (Bağlan) düğmesi gösterir ve tarayıcıdaki oturum açma akışını başlatır. Proje düzeyindeki bir .cursor/mcp.json dosyasında bulunan anahtarı asla sürüm kontrolüne kaydetmeyin; paylaşılan depolar için genel dosyayı veya OAuth kullanın.

6. Gemini'ı bağlayın

Gemini CLI. Google'ın terminal ajanı, uzak sunucu yapılandırmalarını ~/.gemini/settings.json dosyasından (veya bir projedeki .gemini/settings.json dosyasından) alır. Streamable HTTP aktarımını seçmesi için url yerine httpUrl kullanın:

~/.gemini/settings.json
{"mcpServers": {  "listingsapi": {    "httpUrl": "https://listingsapi.com/mcp",    "headers": {      "Authorization": "API <your key>"    },    "timeout": 30000  }}}

OAuth için headers bloğunu "oauth": { "enabled": true } ile değiştirin, CLI'ı başlatın ve /mcp auth listingsapi komutunu çalıştırın. Sunucuyu, bağlantı durumunu ve keşfettiği araçları listelemek için istediğiniz zaman /mcp komutunu çalıştırın.

Gemini uygulaması. Bireysel kullanıcılara yönelik Gemini uygulamasında özel bağlayıcı ayarı yoktur. Özel MCP sunucuları, Gemini Enterprise Business sürümünün ekip yöneticileri tarafından kullanılabilir: business.gemini.google adresinde oturum açın, Settings & help (Ayarlar ve yardım) bölümünü, ardından Manage team (Ekibi yönet) ve Connected apps (Bağlı uygulamalar) bölümlerini açın ve Add MCP Server (MCP sunucusu ekle) düğmesine tıklayın. URL olarak https://listingsapi.com/mcp adresini yapıştırın. Form OAuth bilgilerini ister: yetkilendirme URL'si https://listingsapi.com/oauth/authorize, token URL'si https://listingsapi.com/oauth/token ve kapsamlar read write şeklindedir. Ayrıca bir istemci kimliği ve istemci gizli anahtarı ister. Bu sunucu, gizli anahtarı olmayan genel PKCE istemcileri oluşturur; bu nedenle formda gösterilen yönlendirme URL'siyle bir istemci kaydedin ve form izin veriyorsa gizli anahtar alanını boş bırakın:

Register an OAuth client
curl -s https://listingsapi.com/oauth/register \-H "Content-Type: application/json" \-d '{  "client_name": "Gemini Business",  "redirect_uris": ["<redirect URL shown in the Gemini form>"],  "grant_types": ["authorization_code", "refresh_token"],  "token_endpoint_auth_method": "none"}'

Yanıt client_id içerir. Gemini formunuz gizli anahtarı zorunlu tutuyorsa yukarıdaki Gemini CLI yöntemini kullanın veya bunun yerine Gemini API ile geliştirin.

Gemini API ile geliştirme. Gemini API SDK, bir MCP istemci oturumunu araç olarak kabul eder; böylece bir betik, Gemini modeline aynı araçları sağlayabilir:

gemini_agent.py
import asyncio, osfrom google import genaifrom mcp import ClientSessionfrom mcp.client.streamable_http import streamablehttp_client HEADERS = {"Authorization": "API " + os.environ["LISTINGSAPI_KEY"]} async def main():  gemini = genai.Client()  async with streamablehttp_client("https://listingsapi.com/mcp", headers=HEADERS) as (r, w, _):      async with ClientSession(r, w) as session:          await session.initialize()          reply = await gemini.aio.models.generate_content(              model="gemini-2.5-pro",              contents="Which of my locations have a Google listing that is not live yet?",              config=genai.types.GenerateContentConfig(tools=[session]),          )          print(reply.text) asyncio.run(main())

7. Bağlantıyı doğrulayın

Asistana güvenmeden önce sunucunun size doğrudan yanıt verdiğini doğrulayın. Araç keşfi için anahtar gerekmez; bu nedenle bu çağrı, URL'ye erişebilen herhangi bir istemciyle başarılı olur:

List the tools
curl -s https://listingsapi.com/mcp \-H "Content-Type: application/json" \-H "Accept: application/json, text/event-stream" \-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | head -c 400

Ardından asistanın içinde, hesabınıza erişilmesini gerektiren bir istekte bulunun:

Planımı göstermek, konumlarımı saymak ve bu ayki API kullanımımı raporlamak için listingsapi araçlarını kullanın.

Çalışan bir bağlantı, planınızı ve erişim durumunuzu whoami üzerinden, konum verilerini locations_all üzerinden ve kullanım sayılarını get_usage üzerinden döndürür. Yanlış veya süresi dolmuş bir anahtar, keşif sırasında değil, ilk araç çağrısında Unauthenticated hatası döndürülmesine neden olur.

Bağlantı çalıştığında başlangıç için kullanabileceğiniz ajan talimatları:

  • "İşletme kaydı hataları olan konumlarımı listeleyin ve her hatayı özetleyin."
  • "Son 7 günde gelen ve yanıtlanmamış yorumları gösterin ve her biri için bir yanıt taslağı hazırlayın. Yanıtları henüz göndermeyin."
  • "1800289 numaralı konumun son iki aya ait Google profil analizlerini karşılaştırın."
  • "create-location uç noktasının sözleşmesini okuyun, ardından şu konumu ekleyin: ..."

listingsAPI ajan becerilerini ekleyin

Beceriler, bir görevle eşleştiğinde ajanın yüklediği talimatlardır; böylece ajan kendi iş akışını oluşturmak yerine test edilmiş bir iş akışını izler. MCP sunucusuyla birlikte çalışırlar: sunucu çağrıları yapar, beceri ise hangi çağrıların hangi sırayla yapılacağını belirler. Herkese açık listingsapi-mcp deposundaki beş listingsAPI becerisi skills.sh üzerinde yayımlanır:

BeceriNe yapar
listingsapi-integrationREST veya SDK koduyla uygulamanıza Listings API'yi ekler: kimlik doğrulama, ilk okuma işlemi, konumlar, yayın platformu bağlantıları ve senkronizasyon durumu.
listingsapi-listing-auditKonumları ve bunların işletme kayıtlarını senkronizasyon durumu, canlı bağlantılar ve olası yinelenen kayıtlar açısından kontrol eder, ardından düzeltmeler önerir. Siz bir düzeltmeyi onaylayana kadar yalnızca okuma işlemleri yapar.
listingsapi-review-managementBir yorum kuyruğu oluşturur, yanıtlanmamış yorumlara öncelik verir, yanıt taslakları hazırlar ve yalnızca onayladığınız yanıtları yayımlar.
listingsapi-multi-location-postingSeçtiğiniz konumlar için Google Business Profile ve Facebook'ta duyurular, etkinlikler ve teklifler hazırlar ve yayımlar, ardından her sonucu kontrol eder.
listingsapi-performance-reportingKonumlarınız genelinde salt okunur performans ve yorum raporları oluşturur.

Skills CLI ile beş becerinin tamamını projenize yükleyin:

All skills
npx skills add listings-api/listingsapi-mcp

Veya bir beceriyi adıyla yükleyin ve ajanı -a ile seçin:

One skill, for Claude Code
npx skills add listings-api/listingsapi-mcp --skill listingsapi-integration -a claude-code

Bu ajanlar için -a cursor veya -a codex kullanın ve yalnızca mevcut proje yerine tüm projeler için yüklemek üzere -g ekleyin.

listingsAPI öğesini yapay zekâ araç dizinlerinde bulun

Aynı sunucu, listingsAPI ajan becerisiyle birlikte bu dizinlerde yer alır. İstemcinizin zaten kullandığı dizinden yükleyin. Her MCP sunucusu girdisi https://listingsapi.com/mcp adresine yönlendirir.

DizinListelenen öğe
Claude bağlayıcı diziniClaude bağlayıcısı olarak MCP sunucusu. Connect (Bağlan) seçeneğine tıklayın ve oturum açın.
Resmî MCP kayıt dizinicom.listingsapi/mcp adıyla kayıtlı MCP sunucusu.
Cursor diziniCursor eklentisi olarak MCP sunucusu.
GlamaMCP sunucusu.
SmitheryMCP sunucusu.
MCP.soMCP sunucusu.
mcpservers.orgMCP sunucusu.
ClawHub (OpenClaw)listingsAPI ajan becerisi.
skills.shlistingsAPI ajan becerisi.

Sorun giderme

BelirtiNedenÇözüm
İlk araç çağrısında 401Anahtar yanlış yazılmış, iptal edilmiş veya üstbilgide API sözcüğü aynen ve ardından bir boşlukla yer almıyorAnahtarı /dashboard/keys içinde yeniden oluşturun ve API <key> biçiminde yapıştırın
Yazma işleminde SY90016Read anahtarı veya read kapsamıWrite anahtarıyla yeniden bağlanın veya write kapsamını onaylayın
Retry-After ile birlikte 429Ajan, planınızın izin verdiğinden daha sık çağrı yapıyorAjandan daha küçük gruplar hâlinde çalışmasını isteyin; bkz. İstek hızı sınırları
İstemci sunucuya ulaşamadığını bildiriyorİstemci yalnızca stdio veya SSE destekliyorStreamable HTTP destekleyen bir istemci veya /dashboard/mcp üzerinde gösterilen mcp-remote köprüsünü kullanın
Belgelerde belirtilen bir araç eksikYıkıcı işlem yapan araçlar kullanıma sunulmazArşivleme ve silme işlemleri için REST veya bir SDK kullanın

Sonraki adımlar