AIエージェントをlistingsAPI MCPに接続

Claude、ChatGPT、Cursor、Geminiをホスト型MCPサーバーに接続すると、アシスタントがユーザーと同じツールを呼び出して、ユーザーの拠点、掲載情報、レビューを読み取り、操作できます。

Listings API は、https://listingsapi.com/mcpで Model Context Protocol（MCP）サーバーを提供しています。インストールや実行は不要です。MCP に対応する AI アシスタントは、この URL に接続し、REST エンドポイントごとに1つのツールと、いくつかのドキュメント用ツールを検出して、ユーザーのアカウントで呼び出します。このガイドでは、主要な各クライアントの接続方法と、接続の確認方法を説明します。

1. エージェントが利用できる機能を確認する

サーバーは60を少し超える数のツールを公開しており、その約3分の2は読み取り専用です。ツール名は REST リソースに対応しているため、locations_search、listings_premium、reviews_respond、posts_create_socialは、それぞれ対応するエンドポイントと同じ処理を、同じパラメーターとレスポンス構造で実行します。3つのドキュメント用ツール、search_docs、get_doc、get_endpointを使うと、アシスタントはペイロードの構造を推測する代わりに、ページやエンドポイントの仕様を参照できます。

ツールの分類	例	必要な権限
拠点	`locations_all`, `locations_search`, `locations_create`, `locations_update`	検索には Read、作成と更新には Write
掲載情報	`listings_premium`, `listings_duplicates`, `listings_mark_duplicate`	Read、重複としてマークするには Write
接続済みアカウント	`connected_accounts_list`, `connected_accounts_listings`, `connected_accounts_connect_listing`	Read、接続とインポートには Write
レビュー	`reviews_list`, `reviews_get`, `reviews_respond`, `reviews_analytics`	Read、返信には Write
投稿	`posts_social_post_view`, `posts_create_social`	Read、公開には Write
分析	`analytics_google`, `analytics_facebook`, `analytics_bing`	Read
アカウント	`whoami`, `get_usage`, `get_subscription`, `recent_errors`	Read
ドキュメント	`search_docs`, `get_doc`, `get_endpoint`, `list_endpoints`	不要

投稿の削除や拠点のアーカイブなど、破壊的な操作はツールとして公開されていません。これらの操作には REST API または SDK を使用するため、アシスタントが独自にデータを削除することはできません。

2. クライアントのサインイン方法を選ぶ

各クライアントは、2つの方法のいずれかで認証します。どちらもサーバー側では同じ API キーによる認証になるため、レート制限と使用量のレポートは同じです。

方法	貼り付ける内容	適した用途
API キーヘッダー	静的ヘッダーとして`Authorization: API <your key>`を設定	設定ファイルを管理できる CLI やエディター
OAuth 2.0	何も貼り付けません。クライアントがブラウザーを開き、ユーザーがサインインして`read`または`read write`を承認します	Claude や ChatGPT などのホスト型アシスタント、またはキーを直接保持すべきでないユーザー

OAuth は PKCE を使用する認可コードフローと動的クライアント登録を利用するため、クライアントには事前に発行された認証情報が不要です。メタデータはhttps://listingsapi.com/.well-known/oauth-authorization-serverにあります。スコープはreadとwriteで、スコープを要求しないクライアントにはreadが付与されます。承認するたびに、その接続専用のキーが作成され、他のキーと同様に/dashboard/keysから取り消すことができます。

3. Claude を接続する

Claude.aiと Claude Desktop。 サーバーはコネクターディレクトリに登録されているため、最も簡単な方法は、https://claude.ai/directory/listings-apiを開いて Connect（接続）をクリックすることです。Claude が OAuth フローを実行し、ユーザーがスコープを承認すると、+ ボタンから Connectors（コネクター）を選んでコネクターを有効にしたチャットで、ツールを利用できます。

URL で追加する場合は、Customize（カスタマイズ）、Connectors（コネクター）の順に進み、+、Add custom connector（カスタムコネクターを追加）をクリックして、https://listingsapi.com/mcpを貼り付け、Add（追加）をクリックしてください。サーバーが Claude をクライアントとして自動登録するため、Advanced settings（詳細設定）は空のままにしてください。Team プランと Enterprise プランでは、オーナーが Organization settings（組織設定）、Connectors（コネクター）の順に進んでコネクターを追加し、その後、メンバーがそのコネクターの Connect（接続）をクリックします。Claude はユーザーのマシンからではなく Anthropic のサーバーから接続するため、ホストされている URL が必要です。

Claude Code。 1つのコマンドで、キーを使用してサーバーを追加できます。

Claude Code

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

ブラウザーでサインインする場合は、--headerフラグを省き、Claude Code 内で/mcpを実行してください。チーム全体で共有する.mcp.jsonにサーバーをコミットするには--scope projectを使用し、キーは一緒にコミットしないでください。

4. ChatGPT を接続する

ChatGPT は、Developer mode（開発者モード）をオンにすると、カスタムコネクターとしてリモート MCP サーバーに接続できます。この機能は Plus、Pro、Business、Enterprise、Edu プランで利用でき、無料プランでは利用できません。

プロフィールメニューから Settings（設定）を開き、Developer mode（開発者モード）をオンにします。ビルドによって、Apps & Connectors（アプリとコネクター）または Security and login（セキュリティとログイン）の下にあります。
コネクターのページ（現在のビルドでは Plugins（プラグイン）と表示されます）で、+ または Create（作成）をクリックします。
名前を入力し、サーバー URL として https://listingsapi.com/mcp を貼り付け、認証方式に OAuth を選択します。保存します。
ChatGPT がサインインページを開きます。read または read write を承認します。
新しいチャットでツールメニューを開き、コネクターを選択して、ツールとともに表示されることを確認します。書き込みツールの実行には、引き続き確認プロンプトでの承認が必要です。

Codex CLI。 OpenAI のターミナルエージェントは、~/.codex/config.toml から MCP サーバーの設定を読み込みます。Codex は HTTP サーバーに対して自動的に OAuth を開始し、サーバーが提示するスコープに従うため、ヘッダー行は省略できます。

~/.codex/config.toml

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

5. Cursor を接続する

/dashboard/mcp のダッシュボードページには、Add to Cursor（Cursor に追加）ボタンがあります。このボタンは、サーバー URL とキーが入力済みの Cursor インストールリンクを開くため、1 回のクリックで設定が完了します。

手動で設定する場合は、すべてのプロジェクトで使用するなら ~/.cursor/mcp.json に、1 つのリポジトリ内で使用するならそのリポジトリの .cursor/mcp.json にサーバーを追加します。

~/.cursor/mcp.json

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

代わりに OAuth でサインインするには、headers ブロックを削除します。Cursor の Settings（設定）から MCP を開くと、サーバーの項目に Connect（接続）ボタンが表示され、このボタンからブラウザーで認証フローを開始できます。プロジェクト単位の .cursor/mcp.json にキーを含めてコミットすることは絶対に避けてください。共有リポジトリでは、グローバル設定ファイルまたは OAuth を使用してください。

6. Gemini を接続する

Gemini CLI。 Google のターミナルエージェントでは、リモートサーバーを ~/.gemini/settings.json（またはプロジェクト内の .gemini/settings.json）で設定します。Streamable HTTP トランスポートが選択されるように、url ではなく httpUrl を使用します。

~/.gemini/settings.json

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

OAuth を使用する場合は、headers ブロックを "oauth": { "enabled": true } に置き換え、CLI を起動して /mcp auth listingsapi を実行します。/mcp を実行すると、いつでもサーバー、その接続状態、検出されたツールを一覧表示できます。

Gemini アプリ。 一般ユーザー向けの Gemini アプリには、カスタムコネクターの設定がありません。Gemini Enterprise Business エディションのチーム管理者はカスタム MCP サーバーを利用できます。business.gemini.google でサインインし、Settings & help（設定とヘルプ）、Manage team（チーム管理）、Connected apps（接続済みアプリ）の順に開いて、Add MCP Server（MCP サーバーを追加）をクリックします。URL として https://listingsapi.com/mcp を貼り付けます。フォームでは OAuth の詳細を入力します。認可 URL は https://listingsapi.com/oauth/authorize、トークン URL は https://listingsapi.com/oauth/token、スコープは read write です。クライアント ID とクライアントシークレットの入力も求められます。このサーバーはシークレットを持たない公開 PKCE クライアントを発行するため、フォームに表示されるリダイレクト URL を使ってクライアントを登録し、フォームで許可されていればシークレットは空欄にします。

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"}'

レスポンスには client_id が含まれます。Gemini のフォームでシークレットが必須の場合は、上記の Gemini CLI の手順を使用するか、代わりに Gemini API を使って実装してください。

Gemini API を使った実装。 Gemini API SDK は MCP クライアントセッションをツールとして受け取るため、スクリプトから Gemini モデルに同じツールを提供できます。

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. 接続を確認する

アシスタントに作業を任せる前に、サーバーが直接応答することを確認します。ツールの検出にはキーが不要なため、この呼び出しは URL にアクセスできるクライアントであれば成功します。

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

次に、アシスタント内で、自分のアカウントへのアクセスが必要な操作を依頼します。

listingsapi ツールを使って、私のプランを表示し、拠点数を数え、今月の API 使用量を報告してください。

接続が正常であれば、whoami からプランとアクセス状態、locations_all から拠点データ、get_usage から使用回数が返されます。キーが間違っているか有効期限が切れている場合は、ツールの検出時ではなく、最初のツール呼び出し時に Unauthenticated エラーが返されます。

接続を確認した後に試すプロンプトの例です。

"掲載情報にエラーがある私の拠点を一覧表示し、各エラーを要約してください。"
"過去7日間に届いたレビューのうち、まだ返信していないものを表示し、それぞれの返信案を作成してください。まだ送信しないでください。"
"拠点 1800289 の Google プロフィールの分析データを、直近2か月の月別データで比較してください。"
"create-location エンドポイントの仕様を読んでから、この拠点を追加してください: ..."

listingsAPIのエージェントスキルを追加する

スキルは、タスクが一致したときにエージェントが読み込む指示であり、エージェントは手順を自分で考える代わりに、検証済みのワークフローに従います。スキルはMCPサーバーと連携して動作し、サーバーが呼び出しを実行し、スキルがどの呼び出しをどの順序で実行するかを決定します。公開されているlistingsapi-mcpリポジトリの5つのlistingsAPIスキルが、skills.shで公開されています。

スキル	機能
`listingsapi-integration`	RESTまたはSDKのコードで、認証、最初の読み取り、拠点、掲載先との接続、同期ステータスに対応するListings APIの機能をアプリケーションに追加します。
`listingsapi-listing-audit`	拠点とその掲載情報の同期ステータス、公開ページへのリンク、重複の疑いがある掲載情報を確認し、修正を提案します。修正を承認するまでは読み取り専用です。
`listingsapi-review-management`	レビューの処理キューを作成し、未返信のレビューを優先して返信案を作成し、承認された返信のみを投稿します。
`listingsapi-multi-location-posting`	選択した拠点のGoogle Business ProfileとFacebookに投稿するお知らせ、イベント、特典を準備して公開し、それぞれの結果を確認します。
`listingsapi-performance-reporting`	複数の拠点を対象に、読み取り専用のパフォーマンスレポートとレビューレポートを作成します。

Skills CLIを使用して、5つすべてをプロジェクトにインストールします。

All skills

npx skills add listings-api/listingsapi-mcp

または、名前を指定して1つをインストールし、-aでエージェントを選択します。

One skill, for Claude Code

npx skills add listings-api/listingsapi-mcp --skill listingsapi-integration -a claude-code

該当するエージェントには-a cursorまたは-a codexを使用し、現在のプロジェクトだけでなくすべてのプロジェクトで使えるようにインストールするには、-gを追加します。

AIツールディレクトリでlistingsAPIを探す

同じサーバーが、listingsAPIのエージェントスキルとともに、以下のディレクトリに登録されています。クライアントがすでに使用しているディレクトリからインストールしてください。MCPサーバーの各登録項目は、すべてhttps://listingsapi.com/mcpを参照しています。

ディレクトリ	登録内容
Claudeコネクタディレクトリ	Claudeコネクタとして登録されたMCPサーバーです。Connect（接続）をクリックしてサインインします。
公式MCPレジストリ	`com.listingsapi/mcp`として登録されたMCPサーバーです。
Cursor Directory	Cursorプラグインとして登録されたMCPサーバーです。
Glama	MCPサーバーです。
Smithery	MCPサーバーです。
MCP.so	MCPサーバーです。
mcpservers.org	MCPサーバーです。
ClawHub (OpenClaw)	listingsAPIのエージェントスキルです。
skills.sh	listingsAPIのエージェントスキルです。

トラブルシューティング

症状	原因	対処方法
最初のツール呼び出しで`401`が返されます	キーの入力に誤りがあるか、キーが失効しているか、ヘッダーに文字列`API`とその直後のスペースが正しく指定されていません	`/dashboard/keys`でキーを再作成し、`API <key>`の形式で貼り付けます
書き込み時に`SY90016`が返されます	Readキーまたは`read`スコープを使用しています	Writeキーで再接続するか、`write`を承認します
`429`が`Retry-After`とともに返されます	エージェントの呼び出し頻度が、プランで許可されている上限を超えています	より小さいバッチで処理するようエージェントに指示してください。レート制限を参照してください
サーバーに接続できないとクライアントに表示されます	クライアントがstdioまたはSSEのみに対応しています	Streamable HTTPに対応するクライアント、または`/dashboard/mcp`に記載されている`mcp-remote`ブリッジを使用します
ドキュメントに記載されているツールが見つかりません	破壊的な操作を行うツールは公開されていません	アーカイブと削除にはRESTまたはSDKを使用します

次の手順

連携方法を選ぶ：MCPが適している場合と、RESTまたはSDKのほうが適している場合を説明します。
最初のAPI呼び出しを実行する：キーを取得し、ツールが返すレスポンスの構造を確認します。
Webhookでイベントに対応する：ポーリングの代わりに、プラットフォームからエージェントに通知を送信させます。
アシスタントが報告するコードについては、認証とエラーコードを参照してください。