Integration Module for Google Search Console (GSC) via Claude AI

This specialized utility bridges the capabilities of Google Search Console (GSC) with the Claude Large Language Model. It empowers SEO specialists to interrogate complex Search Console telemetry using conversational language, automating tasks related to property oversight, performance metrics extraction, URL diagnostics, and sitemap lifecycle management.

Key Capabilities for Digital Marketing & SEO Personnel

Site Property Oversight
Catalogue all registered GSC assets.
Retrieve verification status and foundational site metadata.
Provision new domain registrations within the GSC interface.
Decommission existing properties from the account.
Performance Telemetry & Reporting
Uncover the specific organic search queries driving site visitation.
Monitor key indicators: impressions, navigational clicks, and resultant CTRs.
Chart performance trajectories across specified temporal ranges.
Conduct comparative analysis across distinct date intervals to isolate fluctuation drivers.
Data Visualization: Generate illustrative charts and graphs interpreting extracted analytics.
Indexing Status and URL Diagnostics
Diagnose indexing impediments for specific web addresses.
Ascertain the last recorded crawl date for any given page.
Execute batch inspections across multiple URLs to identify systemic issues.
Formulate prescriptive, data-backed steps for remediation of indexing failures.
Sitemap Lifecycle Administration
Enumerate all submitted sitemaps alongside their current processing state.
Initiate the submission of fresh sitemap files directly through the conversational interface.
Detect and report any structural errors or validation warnings present in the sitemaps.
Track the ongoing ingestion status of these navigational files by Google.

Exposed Utility Functions

Once the connection is established, interact with Claude by requesting these specific operations:

Function Call	Action Performed	Required Input Context
`list_properties`	Displays all managed GSC site entities.	None required.
`get_site_details`	Retrieves comprehensive metadata for a chosen domain.	The fully qualified domain URL.
`add_site`	Registers a novel domain within the GSC portfolio.	The fully qualified domain URL.
`delete_site`	Erases a domain record from the GSC portfolio.	The fully qualified domain URL.
`get_search_analytics`	Fetches query/page performance metrics.	Domain URL and the required reporting time window.
`get_performance_overview`	Provides a high-level summary of domain health.	Domain URL and the required reporting time window.
`check_indexing_issues`	Scans a list of pages for Google indexing difficulties.	Domain URL and a list specifying the URLs under review.
`inspect_url_enhanced`	Executes a granular examination of a single URL's status.	Domain URL and the specific page URI to inspect.
`get_sitemaps`	Lists all sitemaps associated with the property.	The fully qualified domain URL.
`submit_sitemap`	Pushes a new or updated sitemap file to Google's indexer.	Domain URL and the URL pointing to the sitemap file.

For a comprehensive roster of all 19 integrated commands and their detailed specifications, instruct Claude to "enumerate tools" post-setup.

Initialization Sequence (No Advanced Coding Skills Assumed)

Phase 1: Secure GSC API Authorization Credentials

Prerequisite: Establishing secure linkage between the connector and your GSC data via API keys/tokens.

Authorization Vectors

Option A: OAuth 2.0 Flow (Recommended) This utilizes your own active Google credentials, mirroring your existing access permissions. Set the environment flag GSC_SKIP_OAUTH to 'true', '1', or 'yes' to force reliance solely on Service Account credentials.

Setup Steps (OAuth): 1. Navigate to the Google Cloud Console and establish a project or select an existing one. 2. Activate the Search Console API library for the selected project. 3. Configure the required OAuth access scope: https://www.googleapis.com/auth/webmasters. 4. Access the "Credentials" management panel. 5. Select "Create Credentials" and choose the "OAuth client ID" type. 6. Configure the necessary OAuth consent screen details. 7. Specify the application type as "Desktop app". 8. Name the client ID and finalize creation. 9. Download the resulting JSON file containing the client secrets (e.g., client_secrets.json). 10. Position this file in the execution directory or set the environmental variable GSC_OAUTH_CLIENT_SECRETS_FILE to its exact location.

Upon the initial execution using OAuth, a browser prompt will appear, requiring you to log in and grant consent. The resulting authorization token is then persisted for subsequent use.

Option B: Service Account Credentials This method relies on a dedicated, non-user account, ideal for automated deployments. Crucially, the service account email address must be manually added as a property user within the target GSC accounts.

Setup Steps (Service Account): 1. In the Google Cloud Console, secure or establish your project. 2. Enable the Search Console API. 3. Navigate to "Credentials" and select "Create Credentials" -> "Service Account". 4. Define the service account parameters and finalize creation. 5. Navigate to the newly created service account, select the "Keys" tab, and add a new key. 6. Select JSON format for the key file and download it, saving it as service_account_credentials.json in the script's root or setting the GSC_CREDENTIALS_PATH environment variable to point to it. 7. Manually grant Search Console permissions to this service account email address for all required properties.

🎬 Visual Guidance: Setup Walkthrough Video

Google Search Console API Setup Tutorial

Click the visual asset above to commence the guided video setup procedure.

Phase 2: Installing Prerequisites

Ensure the following runtime components are available on your operating system:

Python (Must be version 3.11 or higher)
Node.js (Required for specific auxiliary MCP machinery)
Claude Desktop Application (The primary conversational interface)

Verify that both Python and Node.js executables are accessible system-wide.

Phase 3: Acquiring the Connector Module

Secure the necessary source files onto your local workstation. The simplest method is:

Access the repository homepage and click the green "Code" button.
Select the "Download ZIP" option.
Extract the contents into a stable directory (e.g., your User Documents folder).

Alternatively, for Git users:

git clone https://github.com/AminForou/mcp-gsc.git

Phase 4: Environment Configuration and Dependency Installation

Open your command-line interface (Terminal/CMD):

Directory Navigation: Change the working directory to the unzipped/cloned project folder: bash # Example path adjustment: cd ~/Documents/mcp-gsc-main
Virtual Environment Creation: Isolate project dependencies using a dedicated environment: ```bash # Recommended using uv: uv venv .venv

# If uv is absent, install it first: pip install uv # Then create the environment: uv venv .venv

# Standard Python fallback: python -m venv .venv ```

Note: Refer to the section below if the pip command fails during initial tooling setup.

Environment Activation: Engage the isolated environment: ```bash # macOS/Linux: source .venv/bin/activate

# Windows: .venv\Scripts\activate ```

Dependency Installation: Install required Python libraries from the manifest file: ```bash # Using uv: uv pip install -r requirements.txt

# OR using standard pip: pip install -r requirements.txt ```

Troubleshooting 'pip not found': ```bash # Ensure core pip utility is available and updated: python3 -m ensurepip --upgrade python3 -m pip install --upgrade pip

# Attempt dependency installation again: python3 -m pip install -r requirements.txt

# Install uv for future use: python3 -m pip install uv ```

The presence of (.venv) prefixing your command prompt indicates successful activation, ensuring all subsequent installations are scoped locally.

Phase 5: Integrating the Connector into Claude Desktop

Ensure you have the Claude Desktop client running.
Locate and open the configuration file for Claude, using the appropriate command for your OS:

```bash # macOS Path: nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows Path: notepad %APPDATA%\Claude\claude_desktop_config.json ```

Insert the relevant JSON structure below into the file, substituting placeholder paths with your actual local file system locations:

Configuration for OAuth Mode (User Account Authorization)

json { "mcpServers": { "gscServer": { "command": "/ABSOLUTE/PATH/TO/.venv/bin/python", "args": ["/ABSOLUTE/PATH/TO/mcp-gsc-main/gsc_server.py"], "env": { "GSC_OAUTH_CLIENT_SECRETS_FILE": "/ABSOLUTE/PATH/TO/client_secrets.json" } } } }

Configuration for Service Account Mode (Automated Credentials)

json { "mcpServers": { "gscServer": { "command": "/ABSOLUTE/PATH/TO/-main/.venv/bin/python", "args": ["/ABSOLUTE/PATH/TO/mcp-gsc-main/gsc_server.py"], "env": { "GSC_CREDENTIALS_PATH": "/ABSOLUTE/PATH/TO/service_account_credentials.json", "GSC_SKIP_OAUTH": "true" } } } }

Crucial Path Mapping: - The first path must target the Python interpreter inside the activated virtual environment. - The second path must point precisely to gsc_server.py within your unzipped directory structure. - The third path (for service accounts) must reference the downloaded credentials JSON file.

Path Examples (Adapt 'yourname' and directory names): - Mac: Python: /Users/yourname/Project/mcp-gsc/.venv/bin/python | Script: /Users/yourname/Project/mcp-gsc/gsc_server.py - Windows: Python: C:\Users\yourname\Project\mcp-gsc\.venv\Scripts\python.exe | Script: C:\Users\yourname\Project\mcp-gsc\gsc_server.py

Save and Restart: Save the configuration file (Ctrl+O, Enter, Ctrl+X in nano; File > Save in Notepad) and relaunch the Claude Desktop application.
Upon initialization, the GSC command set should now appear as available tools.

Phase 6: Commence SEO Data Interrogation!

With the link active, you can now direct Claude to perform complex data retrieval, analysis, interpretation, and even generate visual aids based on your GSC intelligence.

Tool Name	Illustrative Query	Enhanced Prompt Example
`list_properties`	"List all my GSC properties and tell me which ones have the most pages indexed."	"List all my GSC properties and provide a summary metric showing which asset possesses the highest count of successfully indexed URLs."
`get_site_details`	"Analyze the verification status of mywebsite.com and explain what the ownership details mean."	"Examine the validation protocol for mydomain.net and articulate the implications of the declared ownership hierarchy for site access management."
`add_site`	"Add my new website https://mywebsite.com to Search Console and verify its status."	"Provision the new domain structure https://newsite.org within the GSC interface and confirm initial verification success."
`delete_site`	"Remove the old test site https://test.mywebsite.com from Search Console."	"Permanently retire and purge the deprecated staging site https://staging.olddomain.co.uk from the Search Console inventory."
`get_search_analytics`	"Show me the top 20 search queries for mywebsite.com in the last 30 days, highlight any with CTR below 2%, and suggest title improvements."	"Extract the peak 20 performing search terms for mydomain.com over the preceding month. Identify any queries where the click-through-rate dips below 2.0% and propose specific optimizations for their associated page titles."
`get_performance_overview`	"Create a visual performance overview of mywebsite.com for the last 28 days, identify any unusual drops or spikes, and explain possible causes."	"Generate a chart summarizing domain performance for the preceding four weeks. Pinpoint any statistically significant anomalies (dips or peaks) in overall clicks and hypothesize potential external or internal factors responsible for these deviations."
`check_indexing_issues`	"Check if pages have indexing problems"	"Audit these critical resource endpoints for immediate indexing failures, prioritizing any that signal a 'Discovered - currently not indexed' status: domain.com/serviceA, domain.com/featureB, domain.com/about"
`inspect_url_enhanced`	"Do a comprehensive inspection of mywebsite.com/landing-page and give me actionable recommendations to improve its indexing status."	"Execute a deep-dive diagnostic on the specific URL domain.com/crucial-asset. Deliver a prioritized list of technical SEO adjustments required to guarantee optimal crawl and index acceptance."
`batch_url_inspection`	"Inspect my top 5 product pages, identify common crawling or indexing patterns, and suggest technical SEO improvements."	"Run comprehensive diagnostics on the five highest-traffic product pages. Synthesize recurring themes in any discovered crawl errors and formulate cross-page technical remediation strategies."
`get_sitemaps`	"List all sitemaps for mywebsite.com, identify any with errors, and recommend next steps."	"Provide a full inventory of all registered sitemaps for the property. Flag any entry exhibiting processing errors and outline the necessary corrective actions."
`list_sitemaps_enhanced`	"Analyze all my sitemaps for mywebsite.com, focusing on error patterns, and create a prioritized action plan."	"Conduct a forensic analysis across every submitted sitemap for the domain. Isolate prevalent error typologies and construct a weighted, prioritized plan for their resolution."
`submit_sitemap`	"Submit my new product sitemap at https://mywebsite.com/product-sitemap.xml and explain how long it typically takes for Google to process it."	"Initiate the indexing submission for the product catalogue map located at https://domain.com/prods.xml and clarify the expected latency until Google confirms successful processing."
`get_sitemap_details`	"Check the status of my main sitemap at mywebsite.com/sitemap.xml and explain what the warnings mean for my SEO."	"Query the processing status of the primary sitemap file at domain.com/main.xml and interpret the significance of any non-critical warning flags in the context of organic visibility."
`get_search_by_page_query`	"What search terms are driving traffic to my blog post at mywebsite.com/blog/post-title? Identify opportunities to optimize for related keywords."	"Determine the top organic query set currently generating impressions and clicks for the article at domain.com/article-xyz. Suggest latent semantic indexing opportunities based on high-impression, low-traffic keywords."
`compare_search_periods`	"Compare my site's performance between January and February. What queries improved the most, which declined, and what might explain these changes?"	"Execute a side-by-side comparison of all query performance metrics between the entirety of January and the entirety of February. Detail the top 10 gainers and top 10 losers in click volume and propose causal hypotheses for the shifts."
`get_advanced_search_analytics`	"Analyze my mobile search performance for queries with high impressions but positions below 10, and suggest content improvements to help them rank better."	"Filter performance data to focus exclusively on mobile devices. Target keywords achieving impressions volume exceeding 5000 but maintaining an average position between 11 and 20. Recommend specific content enrichment strategies to push these into the top 10."

Advanced Synthesis Prompts:

"Identify my top twenty landing pages based on organic traffic volume. Subsequently, utilize the indexing tool to verify the crawl status of these pages. Compile a final executive report detailing any instances where high traffic is associated with indexing uncertainty, alongside suggested immediate fixes."
"Chart the domain's overall click trend across the preceding quarter (90 days). Cross-reference this with identified high-growth queries. Then, assess the crawl status of the URLs associated with those growing queries to ensure technical health supports the momentum."
"Perform a comparative review of desktop versus mobile query performance profiles. Visually represent the disparity in CTR and average position using appropriate charting mechanisms. Based on performance gaps, mandate specific, targeted mobile optimization tasks for underperforming URL assets."
"Scan for keywords where the domain currently occupies the second ranking page (positions 11 through 20) but which command significant impression volume coupled with sub-optimal CTR. Inspect the associated landing page URLs and generate refined, high-impact suggestions for Title Tag and Meta Description rewrites aimed at maximizing click acquisition."

Claude will utilize the GSC utilities to retrieve raw datasets, transform this data into comprehensible formats, render supportive visual artifacts, and synthesize pragmatic, actionable recommendations derived directly from the resulting analysis.

Data Interpretation and Visualization Features

Claude is equipped to render your GSC findings visually:

Time-Series Plots: Display metric fluctuations across dates.
Comparative Graphics: Juxtapose performance across different segments or time periods.
Distribution Maps: Illustrate how content ranks across positional bands.
Relational Diagrams: Uncover correlations between disparate performance indicators.
Heat Representations: Employ color gradients for intuitive decoding of large, multi-variable datasets.

Simply preface your analytical request with directives like "visualize the data" or "generate a comparative chart," and the model will deploy the most suitable graphical representation.

Remediation of Common Issues

Python Execution Path Failure

On Unix-like systems (macOS), the default interpreter invocation is frequently python3, which can lead to initialization errors in environments expecting python (like some Node.js wrappers).

Remedy (One-time Alias Creation):

# For macOS users:
sudo ln -s $(which python3) /usr/local/bin/python

# Fallback if the above fails (may require finding the precise Python version directory):
sudo ln -s /Library/Frameworks/Python.framework/Versions/3.11/bin/python3 /usr/local/bin/python

Verification:

python --version

This creates a symbolic link, ensuring commands calling python resolve to your installed python3 binary.

Claude Configuration Malfunctions

If tool invocation fails: 1. Double-check that every file path declared in the configuration block is absolute and perfectly accurate. 2. Confirm that the service account email has been explicitly authorized on the relevant GSC properties. 3. Always perform a full restart of the Claude Desktop application after modifying the configuration file. 4. Review the textual response from Claude immediately after a failed tool attempt; error codes or specific failure messages are often included. 5. Verify the virtual environment activation status.

Unforeseen Operational Difficulties

Should you encounter unexpected behavior during setup or utilization:

Capture the entirety of the error output generated by the system.
Present this complete error log, along with a detailed description of the action you intended to perform, your operating system, and a summary of troubleshooting steps already attempted, to a generative AI model (like ChatGPT or Claude).
These models are highly effective at diagnosing esoteric technical failures by leveraging collective knowledge regarding common environmental setups.

Remember that the vast majority of implementation hurdles possess documented, straightforward fixes.

Contribution Guidelines

Bugs discovered or feature enhancement proposals are eagerly anticipated. Please submit issues or contribute code via a pull request on the associated GitHub repository.

Licensing Information

This software is distributed under the terms of the MIT License. Refer to the included LICENSE file for full particulars.

Claude-GSC-Connector

Author

AminForou

Quick Info

Actions

Tags