Google Search Console MCP Server

A Model Context Protocol (MCP) server that provides AI agents with access to Google Search Console data.

Quick Start

For users with an MCP-compatible client (like Claude Desktop):

npx search-console-mcp

---

Table of Contents

• Features
• Installation
• Google Cloud Setup
• MCP Client Configuration
• Local Development
• Tools Reference
• Resources
• Prompts

---

Features

• Sites Management: List, add, and delete sites
• Sitemaps: List, submit, get, and delete sitemaps
• Search Analytics: Query performance data with advanced filtering and pagination
• Period Comparison: Compare metrics between two date ranges
• Top Queries/Pages: Get top performing queries and pages
• URL Inspection: Check indexing status of specific URLs
• AI Documentation: Built-in docs for AI agents to understand GSC concepts

---

Installation

Option 1: Use with npx (Recommended)

No installation needed. Configure your MCP client to run:

npx search-console-mcp

Option 2: Global Install

npm install -g search-console-mcp
search-console-mcp

Option 3: Clone for Development

git clone https://github.com/saurabhsharma2u/search-console-mcp.git
cd search-console-mcp
npm install
npm run build
node dist/index.js

---

Google Cloud Setup

Step 1: Create a Google Cloud Project

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Search Console API:
   • Go to APIs & Services > Library
   • Search for "Google Search Console API"
   • Click Enable

Step 2: Create a Service Account

1. Go to APIs & Services > Credentials
2. Click Create Credentials > Service Account
3. Fill in the details and click Create
4. Skip the optional steps and click Done
5. Click on the service account email to open it
6. Go to the Keys tab > Add Key > Create new key
7. Select JSON and download the key file

Step 3: Grant Access in Search Console

1. Go to Google Search Console
2. Select your property
3. Go to Settings > Users and permissions
4. Click Add user
5. Enter the service account email (e.g., my-service@project.iam.gserviceaccount.com)
6. Set permission to Full (for write operations) or Restricted (read-only)

Step 4: Configure Credentials

Option A: File-based (Local Development)

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"

Option B: Environment Variables (Serverless/Cloudflare)

export GOOGLE_CLIENT_EMAIL="your-service-account@project.iam.gserviceaccount.com"
export GOOGLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"

---

MCP Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["search-console-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json"
      }
    }
  }
}

Generic MCP Client

{
  "name": "google-search-console",
  "command": "npx",
  "args": ["search-console-mcp"],
  "env": {
    "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json"
  }
}

---

Local Development

Setup

# Clone the repository
git clone https://github.com/saurabhsharma2u/search-console-mcp.git
cd search-console-mcp

# Install dependencies
npm install

# Create .env file
cp .env.example .env
# Edit .env with your credentials

# Build
npm run build

# Run tests
npm test

# Run the server
node dist/index.js

Project Structure

src/
├── index.ts          # MCP server entry point
├── google-client.ts  # Google API authentication
├── errors.ts         # Error handling utilities
├── docs/             # Embedded documentation for AI
│   ├── dimensions.ts
│   ├── filters.ts
│   ├── search-types.ts
│   └── patterns.ts
└── tools/            # Tool implementations
    ├── sites.ts
    ├── sitemaps.ts
    ├── analytics.ts
    └── inspection.ts

---

Tools Reference

Sites

Tool	Description	Arguments
sites_list	List all sites	none
sites_add	Add a site	siteUrl
sites_delete	Delete a site	siteUrl
sites_get	Get site details	siteUrl

Sitemaps

Tool	Description	Arguments
sitemaps_list	List sitemaps	siteUrl
sitemaps_get	Get sitemap details	siteUrl, feedpath
sitemaps_submit	Submit sitemap	siteUrl, feedpath
sitemaps_delete	Delete sitemap	siteUrl, feedpath

Analytics

Tool	Description	Arguments
analytics_query	Query search analytics with filters	siteUrl, startDate, endDate, dimensions?, type?, limit?, startRow?, filters?
analytics_performance_summary	Get aggregate metrics for N days	siteUrl, days?
analytics_compare_periods	Compare two date ranges	siteUrl, period1Start, period1End, period2Start, period2End
analytics_top_queries	Get top queries	siteUrl, days?, limit?, sortBy?
analytics_top_pages	Get top pages	siteUrl, days?, limit?, sortBy?

Inspection

Tool	Description	Arguments
inspection_inspect	Inspect URL index status	siteUrl, inspectionUrl, languageCode?

PageSpeed Insights

Tool	Description	Arguments
pagespeed_analyze	PageSpeed Insights scores (performance, accessibility, SEO)	url, strategy? (mobile/desktop)
pagespeed_core_web_vitals	Core Web Vitals for mobile & desktop (LCP, FID, CLS, etc.)	url

SEO Insights

Tool	Description	Arguments
seo_recommendations	Generate actionable SEO recommendations	siteUrl, days?
seo_low_hanging_fruit	Find keywords at positions 5-20 with high impressions	siteUrl, days?, minImpressions?, limit?
seo_cannibalization	Detect pages competing for the same keywords	siteUrl, days?, minImpressions?, limit?
seo_quick_wins	Find pages close to page 1 (positions 11-20)	siteUrl, days?, minImpressions?, limit?

---

Resources

AI agents can read these built-in documentation and data resources:

URI	Description
sites://list	List of all sites (JSON)
sitemaps://list/{siteUrl}	Sitemaps for a specific site (JSON)
analytics://summary/{siteUrl}	Performance summary for a site (JSON)
docs://dimensions	Available dimensions reference
docs://filters	Filter operators and examples
docs://search-types	Search types (web, image, video, etc.)
docs://patterns	Common usage patterns and recipes

---

Prompts

Pre-configured analysis workflows for AI agents:

Prompt	Description	Arguments
analyze-site-performance	Analyze site's 28-day performance	siteUrl
compare-performance	Compare this week vs last week	siteUrl
find-declining-pages	Find pages losing traffic	siteUrl
keyword-opportunities	Find low-CTR high-impression queries	siteUrl
new-content-impact	Analyze new content performance	siteUrl, pageUrl
mobile-vs-desktop	Compare device performance	siteUrl

---

Contributing

See CONTRIBUTING.md for contribution guidelines.

Roadmap

See ROADMAP.md for planned features.

License

MIT - see LICENSE