MCP HubMCP Hub
seotesting-com

gsc-mcp-server

by: seotesting-com

gsc mcp server

7created 14/03/2025
Visit
gsc

📌Overview

Purpose: The framework allows users to set up an MCP (Model Context Protocol) server to leverage Google Search Console data for enhanced SEO analysis and reporting.

Overview: This guide provides a step-by-step process to configure an MCP server, integrate it with Claude Desktop, and utilize Google Search Console insights to optimize website performance through advanced analytics and visual reporting.

Key Features:

  • Data Analysis Tools: Offers multiple tools to analyze various aspects of SEO performance, including identifying high impressions with low click-through rates and comparing traffic over different time periods.

  • Visualization Capabilities: Enables users to generate various types of visual reports, such as bar charts and line graphs, to easily analyze trends and performance metrics.

Google Search Console MCP Server

🚀 Introduction: Setting Up MCP Server

In this tutorial, we’ll walk you through setting up your own MCP (Model Context Protocol) server, adding it to Claude Desktop, and integrating it with Google Search Console (GSC) data. This setup enables you to compare time periods to identify SEO improvements, generate visual reports like bar charts and line graphs, and uncover optimization opportunities by analyzing click-through rates, impressions, and ranking shifts.

Let’s get started! 🚀

🔹 What We'll Cover

  1. Generate Google Cloud Credentials – Create and download a service account JSON key to authenticate API access.
  2. Install Required Tools – Ensure Python, pip, uv, and Git (optional) are installed on your system.
  3. Set Up the MCP Server – Clone the repository, configure your environment, and install the MCP server.
  4. Enable Search Console Insights – Verify MCP server running in Claude Desktop and start using advanced search analytics tools.

By the end of this guide, Claude will automatically connect to the MCP server, enabling you to run queries, visualize data, and optimize your website’s search performance with ease.

🔹 What You Need to Know

This tutorial is beginner-friendly; no advanced technical skills are required. However, you should be comfortable running commands in the command line (terminal or command prompt).

Example commands you'll use:

python --version
git clone <repository-url>

Follow the instructions step by step, and you'll be good to go.

🎯 Part 1 - Generate a JSON Credentials File

Follow these steps to create and download a service account JSON key from Google Cloud Console. If you already have this file, skip this part.

1. Go to Google Cloud Console

Visit https://console.cloud.google.com/

2. Select Your Project

  • Click on the project selector at the top.
  • Select an existing project or create a new one.

If creating a new project:

Enable Search Console API

  • Ensure your new project is selected.
  • Go to APIs and Services.
  • Search for Google Search Console API and click Enable.
  • Return to the dashboard.

3. Open the IAM & Admin Section

  • In the left menu, go to IAM & Admin > Service Accounts.

4. Create a New Service Account

  • Click Create Service Account.
  • Enter a name (e.g., my-app-service-account).
  • Click Create and Continue.

5. Assign Permissions

  • Choose a role (e.g., Editor, Owner).
  • Click Continue.

6. Skip Granting Users Access (Optional)

  • Click Done.

7. Generate the JSON Key

  • Find your service account in the list.
  • Click the 3 dots (â‹®) on the right and select Manage Keys.
  • Click Add Key > Create New Key.
  • Choose JSON format and click Create.
  • The JSON file will download automatically.
  • Copy the path of the JSON file.

8. Add the Service Account to Google Search Console

  1. Open https://search.google.com/search-console
  2. Select the website property.
  3. Click Settings (bottom left).
  4. Under Users and Permissions, click Add User.
  5. Enter the service account email from step 4.
  6. Assign permissions:
    • Restricted (view data only) or
    • Full (view & manage property).
  7. Click Add.

🎯 Part 2 - Install Required Tools

Before starting with MCP server, ensure you have the following tools installed:

1. Check if Python is Installed

Run:

  • On Windows: 
    python --version
  • On Linux/macOS: 
    python3 --version

If not installed, download it from https://www.python.org/downloads/

2. Check if pip is Installed

Run:

  • On Windows: 
    pip --version
  • On Linux/macOS: 
    pip3 --version

If not installed, see https://pip.pypa.io/en/stable/installation/

3. Check if uv is Installed

Run:

uv --version

If not installed, see https://docs.astral.sh/uv/getting-started/installation/

4. Check if Claude Desktop is Installed

If not installed, download from https://claude.ai/

5. Check if Git is Installed (optional)

Run:

git --version

If not installed, download from https://git-scm.com/downloads
You can also download the project files as a ZIP if you do not want to install Git.

🎯 Part 3 - Add the MCP Server to Claude Desktop

Setup Instructions

1. Clone the Repository

Open a terminal in the directory you want files downloaded and run:

git clone https://github.com/seotesting-com/gsc-mcp-server.git
cd gsc-mcp-server

If you don't have Git, download the ZIP file manually from the repository website.

2. Create and Activate a Virtual Environment

# Windows
uv venv
.venv\Scripts\activate

# macOS/Linux
uv venv
source .venv/bin/activate

3. Install Dependencies

uv sync

4. Install MCP Server

Add the path to your JSON credentials file and run:

mcp install server.py -v GOOGLE_APPLICATION_CREDENTIALS=<path to credentials file>

Replace <path to credentials file> with your actual JSON credentials file path, e.g. C:\Users\Me\Downloads\credentials.json or /Users/me/Downloads/credentials.json.

5. Restart Claude Desktop

You may need to quit Claude processes from Task Manager or Activity Monitor before restarting.

🎯 Part 4 - Get Search Console Insights

Open Claude Desktop. If configured correctly, 5 additional tools will appear in the chat box.

You can ask Claude search console analytics queries. Claude will request permission before using a tool; click 'allow' to proceed.

Sample Prompts

Getting Started:

  • List all my verified sites in Google Search Console
  • Show me search analytics for example.com from January 1 to January 31, 2025
  • Compare search performance for example.com between last month and the previous month
  • What are my top 10 pages by clicks for the last 30 days?

Data Visualization:

  • Generate a bar chart of my top 5 performing pages by clicks for the past month
  • Create a line graph showing impression trends over the last 90 days
  • Visualize the CTR comparison between mobile and desktop traffic
  • Plot a heatmap of search performance by country
  • Create a pie chart showing traffic distribution by device type

Search Console Analysis:

  • Identify keywords with high impressions but low CTR for optimization
  • Show pages that have dropped in rankings over the last month
  • Find new keywords the site started ranking for in the past 30 days
  • Analyze mobile pages with biggest performance gaps compared to desktop
  • Show queries where I rank on page 2 that I could push to page 1
  • Identify seasonal trends in search traffic
  • Compare organic traffic before and after a site redesign
  • Show countries with highest growth potential based on impressions vs. clicks
  • Analyze correlation between average position and CTR
  • Generate prioritized optimization opportunities list

Available Tools

  • list_sites: Lists all verified sites in your Google Search Console account.

  • query_search_analytics:
    Parameters:

    • site_url (e.g. https://www.example.com/)
    • start_date (YYYY-MM-DD)
    • end_date (YYYY-MM-DD)
    • dimensions (query, page, device, country, date)
    • search_type (web, image, video, news, discover, googleNews)
    • row_limit (max 25000)

  • compare_time_periods:
    Parameters:

    • site_url
    • current_start_date
    • current_end_date
    • previous_start_date
    • previous_end_date
    • dimensions
    • search_type
    • row_limit

  • get_top_performing_content:
    Parameters:

    • site_url
    • start_date
    • end_date
    • metric (clicks, impressions, ctr, position)
    • limit

  • get_search_trends:
    Parameters:

    • site_url
    • start_date
    • end_date
    • interval (day, week, month)

🛠 Troubleshooting

1. Restart Claude Desktop

If tools don’t appear immediately, restart Claude Desktop. You might need to end Claude from Task Manager (Windows) or Activity Monitor (Mac) before restarting.

2. Wait a Few Minutes

After setup, tools may take a few minutes to load.

3. Check JSON Credentials File

Ensure your service account JSON file is in an accessible folder, not in restricted locations like C:\Program Files\ (Windows) or ~/Library/ (macOS). Consider placing it in Documents or Desktop.

4. Check Claude Desktop Configuration

Go to File > Settings > Developer tab in Claude Desktop, click on Search Console Analytics and check if status is 'running'. If not, error details will be shown.

Click Edit Config and open claude_desktop_config.json in a text editor. It should contain:

{
  "mcpServers": {
    "Search Console Analytics": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "google-api-python-client",
        "--with",
        "google-auth",
        "--with",
        "mcp[cli]",
        "--with",
        "pandas",
        "mcp",
        "run",
        "C:\\Documents\\gsc-mcp-server\\server.py"
      ],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "C:\\Users\\Path\\To\\Credentials\\gscaccess-credentials.json"
      }
    }
  }
}

Update file paths to your environment, using escaped backslashes on Windows. Save and restart Claude.

Mac Users: Fixing "spawn uv ENOENT" Error

This error means uv is not installed or not found in the system path.

1. Update Claude Configuration

Open Claude Desktop, go to File > Settings > Developer, click Search Console Analytics, then Edit Config.

Find "command": "uv" and replace "uv" with the full path to the uv executable, usually:

/Users/YOURUSERPROFILENAME/.local/bin/uv

Run this command to find uv path:

which -a uv

If no suitable path, install uv following the installation guide.

Save and restart Claude Desktop.

2. Alternative Installation with Homebrew

If problems persist, install uv with Homebrew:

brew install uv

After installation, retry configuring Claude Desktop.

Summary

This guide helps you:

  • Generate Google Cloud service account credentials.
  • Install necessary tools (Python, pip, uv, Claude Desktop).
  • Set up and activate MCP server with Google Search Console data.
  • Use Claude Desktop to analyze SEO data with intuitive prompts and visualization tools.

Feel free to reach out if you encounter issues or want to extend functionality. Happy optimizing! 🚀