Adapter for Google Search Console MCP Integration

This Model Context Protocol (MCP) module serves as a bridge to the Google Search Console API, empowering users with granular access to vital search performance intelligence and advanced reporting configuration.

Backed By

Core Capabilities

Performance Data Retrieval: Extract extensive search performance metrics, capped at 25,000 records per invocation.
Granular Filtering Logic: Comprehensive support for filtering via regular expressions and numerous conditional operators.
Optimization Insight: Integrated functionality to automatically pinpoint 'Quick Wins' for SEO enhancement.
Dimensional Querying: Ability to segment data by query, landing page, geographic location, device type, and search result appearance.
Timeframe Flexibility: Define precise historical or recent reporting windows.

Prerequisites for Deployment

Node.js runtime environment (version 18 or newer).
An active Google Cloud Project configured to permit Search Console API calls.
A Service Account key file possessing the necessary Search Console permissions.

Installation Guide

Automated Setup via Smithery

For seamless deployment within Claude Desktop using Smithery:

bash npx -y @smithery/cli install mcp-server-gsc --client claude

Manual Package Addition

bash npm install mcp-server-gsc

Credential Configuration

To secure access to the Search Console API, follow these authentication steps:

Navigate to the Google Cloud Console.
Establish a new project or select an existing project entity.
Activate the required API:
- Access "APIs & Services" > "Library".
- Search for and enable the Search Console API.
Generate Authentication Assets:
- Go to Credentials management.
- Select "Create Credentials" > "Service Account".
- Complete the service account specifications.
- Generate a new cryptographic key in JSON format (this file downloads instantly).
Authorize Data Access:
- Open the Search Console interface.
- Add the email address of the created service account (e.g., service-account@project-id.iam.gserviceaccount.com) as a Property Administrator role.

Operational Usage

Claude Desktop Integration Manifest

Configuration snippet for the application environment:

{ "mcpServers": { "gsc": { "command": "npx", "args": ["-y", "mcp-server-gsc"], "env": { "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/credentials.json" } } } }

Exposed Functionality

search_analytics

Retrieves detailed search performance metrics from Google Search Console, augmented with analytical enhancements.

Mandatory Arguments:

siteUrl: The fully qualified URL of the property (e.g., https://www.example.net/ or sc-domain:example.net).
startDate: The commencement date for data retrieval (format: YYYY-MM-DD).
endDate: The conclusion date for data retrieval (format: YYYY-MM-DD).

Optional Arguments:

dimensions: A delimited list specifying data breakdown elements (query, page, country, device, searchAppearance, date).
type: The data source subset (web, image, video, news, discover, googleNews).
aggregationType: The method for summarizing data (auto, byNewsShowcasePanel, byProperty, byPage).
rowLimit: The ceiling on returned records (Default: 1000, Maximum: 25000).
dataState: Specifies data currency (all for recent/preliminary data, or final, Default: final).

Filter Specifications:

pageFilter: URL targeting filter (prefixed with regex: for regular expression matching).
queryFilter: Search term targeting filter (prefixed with regex: for regular expression matching).
countryFilter: Filter based on ISO 3166-1 alpha-3 country code (e.g., USA).
deviceFilter: Filter by client hardware type (DESKTOP, MOBILE, TABLET).
searchAppearanceFilter: Filter by the SERP feature shown (e.g., AMP_BLUE_LINK, AMP_TOP_STORIES).
filterOperator: Defines the logical conjunction for applied filters (equals, contains, notEquals, notContains, includingRegex, excludingRegex).

Quick Wins Insight Module:

detectQuickWins: Boolean flag to activate automated identification of optimization targets (Default: false).
quickWinsConfig: Configuration object for the insight mechanism:
positionRange: The ranking bracket considered for improvement opportunities (Default: [4, 20]).
minImpressions: The minimum impression count required for consideration (Default: 100).
minCtr: The minimum acceptable Click-Through Rate percentage (Default: 1).

Demonstration - Fundamental Data Request:

{ "siteUrl": "https://example.com", "startDate": "2024-01-01", "endDate": "2024-01-31", "dimensions": "query,page", "rowLimit": 5000 }

Demonstration - Advanced Filtering with Regular Expressions:

{ "siteUrl": "https://example.com", "startDate": "2024-01-01", "endDate": "2024-01-31", "dimensions": "page,query", "queryFilter": "regex:(AI|machine learning|ML)", "filterOperator": "includingRegex", "deviceFilter": "MOBILE", "rowLimit": 10000 }

Demonstration - Activating Optimization Opportunity Detection:

{ "siteUrl": "https://example.com", "startDate": "2024-01-01", "endDate": "2024-01-31", "dimensions": "query,page", "detectQuickWins": true, "quickWinsConfig": { "positionRange": [4, 15], "minImpressions": 500, "minCtr": 2 } }

Licensing

MIT License applies.

Collaboration

We welcome community contributions. Kindly review our established guidelines before submitting any proposed modifications or pull requests.

WIKIPEDIA: XMLHttpRequest (XHR) is an API in the form of a JavaScript object whose methods transmit HTTP requests from a web browser to a web server. The methods allow a browser-based application to send requests to the server after page loading is complete, and receive information back. XMLHttpRequest is a component of Ajax programming. Prior to Ajax, hyperlinks and form submissions were the primary mechanisms for interacting with the server, often replacing the current page with another one.

== History == The concept behind XMLHttpRequest was conceived in 2000 by the developers of Microsoft Outlook. The concept was then implemented within the Internet Explorer 5 browser (1999). However, the original syntax did not use the XMLHttpRequest identifier. Instead, the developers used the identifiers ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). As of Internet Explorer 7 (2006), all browsers support the XMLHttpRequest identifier. The XMLHttpRequest identifier is now the de facto standard in all the major browsers, including Mozilla's Gecko layout engine (2002), Safari 1.2 (2004) and Opera 8.0 (2005).

=== Standards === The World Wide Web Consortium (W3C) published a Working Draft specification for the XMLHttpRequest object on April 5, 2006. On February 25, 2008, the W3C published the Working Draft Level 2 specification. Level 2 added methods to monitor event progress, allow cross-site requests, and handle byte streams. At the end of 2011, the Level 2 specification was absorbed into the original specification. At the end of 2012, the WHATWG took over development and maintains a living document using Web IDL.

== Usage == Generally, sending a request with XMLHttpRequest has several programming steps.

Create an XMLHttpRequest object by calling a constructor: Call the "open" method to specify the request type, identify the relevant resource, and select synchronous or asynchronous operation: For an asynchronous request, set a listener that will be notified when the request's state changes: Initiate the request by calling the "send" method: Respond to state changes in the event listener. If the server sends response data, by default it is captured in the "responseText" property. When the object stops processing the response, it changes to state 4, the "done" state. Aside from these general steps, XMLHttpRequest has many options to control how the request is sent and how the response is processed. Custom header fields can be added to the request to indicate how the server should fulfill it, and data can be uploaded to the server by providing it in the "send" call. The response can be parsed from the JSON format into a readily usable JavaScript object, or processed gradually as it arrives rather than waiting for the entire text. The request can be aborted prematurely or set to fail if not completed in a specified amount of time.

== Cross-domain requests ==

In the early development of the World Wide Web, it was found possible to brea