gsc_query
Retrieve top search queries and pages with performance metrics from Google Search Console for a specified site and date range, customizable by dimensions like device or country.
Instructions
Search Console performance report (top queries and pages with metrics).
Args: site_url: Site URL (e.g. "https://example.com/" or "sc-domain:example.com"). date_from: Start date (YYYY-MM-DD). date_to: End date (YYYY-MM-DD). dimensions: Comma-separated dimensions (query, page, country, device, date). row_limit: Maximum rows (default 100, max 25000).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| site_url | Yes | ||
| date_from | Yes | ||
| date_to | Yes | ||
| dimensions | No | query | |
| row_limit | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- The main handler function for the 'gsc_query' tool. Calls the Google Search Console Search Analytics API to fetch performance data (clicks, impressions, CTR, position) grouped by user-specified dimensions (query, page, country, device, date). Returns formatted JSON results.
@mcp.tool() def gsc_query( site_url: str, date_from: str, date_to: str, dimensions: str = "query", row_limit: int = 100, ) -> str: """Search Console performance report (top queries and pages with metrics). Args: site_url: Site URL (e.g. "https://example.com/" or "sc-domain:example.com"). date_from: Start date (YYYY-MM-DD). date_to: End date (YYYY-MM-DD). dimensions: Comma-separated dimensions (query, page, country, device, date). row_limit: Maximum rows (default 100, max 25000). """ encoded = urllib.parse.quote(site_url, safe="") dims = [d.strip() for d in dimensions.split(",")] data = _api_post( f"{BASE}/sites/{encoded}/searchAnalytics/query", { "startDate": date_from, "endDate": date_to, "dimensions": dims, "rowLimit": min(row_limit, 25000), }, ) results = [] for row in data.get("rows", []): entry = {} for i, dim in enumerate(dims): entry[dim] = row["keys"][i] entry["clicks"] = row.get("clicks", 0) entry["impressions"] = row.get("impressions", 0) entry["ctr"] = f"{row.get('ctr', 0):.4f}" entry["position"] = f"{row.get('position', 0):.1f}" results.append(entry) return json.dumps(results, indent=2, ensure_ascii=False) - src/google_search_console_mcp/server.py:102-103 (registration)Registration of gsc_query as an MCP tool via the @mcp.tool() decorator on line 114. (The decorator itself is at line 102 for the prior tool; gsc_query uses the same @mcp.tool() pattern on line 114.)
@mcp.tool() def gsc_site_details(site_url: str) -> str: - The _api_post helper function used by gsc_query to POST JSON to the Google Webmasters API with OAuth Bearer token authentication.
def _api_post(url: str, body: dict) -> dict: data = json.dumps(body).encode() req = urllib.request.Request( url, data=data, headers={ "Authorization": f"Bearer {_get_token()}", "Content-Type": "application/json", }, ) with urllib.request.urlopen(req) as resp: return json.loads(resp.read()) - src/google_search_console_mcp/server.py:8-8 (registration)The FastMCP server instance (mcp) used by @mcp.tool() to register gsc_query as a tool.
from mcp.server.fastmcp import FastMCP