The most powerful Google Search Console MCP server -- analyzes data like an SEO professional with benchmarks, recommendations, and actionable insights.
Just ask it to analyze your Google Search Console.
Ask Claude to analyze your Search Console data |
Here's a sample result |
- 27 tools across 7 categories covering every aspect of Google Search Console
- Smart analysis engine with CTR benchmarks, trend detection, query intent classification, opportunity scoring, and a recommendation engine
- In-memory caching for fast repeat queries
- Rate limiting (20 req/s with burst of 30) to stay within API quotas
- Dual transport -- stdio (default) and HTTP for flexible integration
- Auto-detecting authentication -- service account, OAuth, or auto-detect from
credentials.json
- Go to Google Cloud Console
- Create a new project (or select an existing one)
4. Create credentials
- Go to the project you created
- Click on Credentials in the sidebar
- Create a service account, name it anything, click continue
|
- Open the service account
|
- Click on the Keys tab
|
- Click Add Key > Create New Key and select JSON. Save it somewhere familiar and try to rename it to something searchable (e.g.
awesome-gsc-service-account.json)
|
|
5. Grant access
- Open Google Search Console
- Go to Settings > Users and permissions
- Add the service account email as an Owner or Full
|
You're almost done. Now we will just refrence the JSON file you downloaded in step 4 (Create credentials).
Claude Code
claude mcp add awesome-gsc -- npx -y awesome-gsc-mcp \
-e GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.jsonTip: Can't find your key file? Run this to locate it:
claude -p "find the path of most recently downloaded .json file in ~/Desktop, ~/Documents, and ~/Downloads"
Claude Desktop
Paste this whole block into Terminal, hit Enter, then restart Claude Desktop.
cat > ~/Library/Application\ Support/Claude/claude_desktop_config.json << 'EOF'
{
"mcpServers": {
"awesome-gsc": {
"command": "npx",
"args": ["-y", "awesome-gsc-mcp"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "{Path to your json file}"
}
}
}
}
EOFHere is an example:
"GOOGLE_APPLICATION_CREDENTIALS": "/Users/Magdoub/Desktop/mobilevitals-service.json"
Cursor
Config file: .cursor/mcp.json in your project root (or ~/.cursor/mcp.json globally)
{
"mcpServers": {
"awesome-gsc": {
"command": "npx",
"args": ["-y", "awesome-gsc-mcp"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account-key.json"
}
}
}
}Windsurf
Config file: ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"awesome-gsc": {
"command": "npx",
"args": ["-y", "awesome-gsc-mcp"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account-key.json"
}
}
}
}Troubleshooting
| Error | Fix |
|---|---|
401 Token has been expired or revoked |
Delete ~/.awesome-gsc-mcp/token.json and re-authorize |
403 User does not have sufficient permission |
Add the service account email as Owner in Search Console > Settings > Users and permissions |
403 Forbidden with OAuth |
Add yourself as a test user in Google Cloud Console > OAuth consent screen, or publish the app |
Could not load the default credentials |
Check that GOOGLE_APPLICATION_CREDENTIALS points to a valid key file |
All 27 tools organized by category
| Tool | Description |
|---|---|
list_properties |
List all Search Console properties accessible to the authenticated account |
get_property_details |
Get detailed information about a specific property |
add_property |
Add a new site to Search Console |
delete_property |
Remove a site from Search Console |
| Tool | Description |
|---|---|
get_search_analytics |
Query raw search analytics data with flexible parameters (dimensions, filters, date ranges) |
get_performance_summary |
High-level performance overview with automatic period-over-period comparison |
compare_periods |
Compare search performance between two custom date periods side by side |
get_top_queries |
Top search queries by clicks with CTR benchmark analysis |
get_top_pages |
Top pages by clicks with CTR analysis and recommendations |
get_traffic_by_device |
Traffic breakdown by device type (desktop, mobile, tablet) with mobile-first insights |
| Tool | Description |
|---|---|
find_quick_wins |
Find "money on the table" SEO opportunities: CTR gaps, almost-page-1 queries, quick position gains |
find_declining_content |
Find pages and queries losing traffic with root cause diagnosis |
find_ctr_opportunities |
Pages with CTR significantly below benchmarks, with position-specific recommendations |
find_content_gaps |
Content creation opportunities: homepage-ranking queries, zero-click queries, new emerging queries |
find_what_to_build_next |
Intent-based content planning: questions, comparisons, problems, buying signals grouped by topic cluster |
| Tool | Description |
|---|---|
inspect_url |
Inspect a URL for indexing status, crawl info, mobile usability, and rich results |
batch_inspect_urls |
Inspect multiple URLs in one call |
check_indexing_issues |
Identify common indexing problems across your site |
| Tool | Description |
|---|---|
list_sitemaps |
List all sitemaps submitted for a property |
get_sitemap_details |
Get detailed information about a specific sitemap |
submit_sitemap |
Submit a new sitemap to Search Console |
delete_sitemap |
Remove a sitemap from Search Console |
| Tool | Description |
|---|---|
analyze_query_landscape |
Intent distribution, branded vs non-branded split, position bucket analysis |
find_new_queries |
Discover emerging and truly new queries between periods |
find_cannibalization |
Find multiple pages competing for the same query |
| Tool | Description |
|---|---|
weekly_seo_report |
Full weekly SEO performance report with trends, top movers, and recommendations |
seo_health_check |
Comprehensive health check with a letter grade and prioritized action items |
Once connected to Claude, try these natural language prompts. Copy any of them as-is.
List all my Search Console properties
How is example.com doing this month?
Give me a performance summary for the last 3 months
What are my top 20 queries by clicks?
Show me traffic breakdown by device
Compare this month's performance vs last month
What are my top pages for mobile traffic?
Show me search performance for image search
Find quick win SEO opportunities for my site
Which pages have CTR below benchmarks?
Find pages that are almost on page 1 of Google
What queries could I get more clicks from with better titles?
What content should I create next?
What questions are people searching that I should answer?
Find content gaps — queries ranking on my homepage that need dedicated pages
Show me new and emerging queries in the last month
What comparison and "best of" queries is my site appearing for?
Which pages are losing traffic and why?
Find keyword cannibalization issues
Are there any indexing issues on my top pages?
Inspect the URL example.com/blog/my-post for indexing problems
Which of my pages are not indexed?
List all my submitted sitemaps
Submit my new sitemap at example.com/sitemap.xml
Check indexing status for my top 50 pages
Batch inspect these URLs: [url1, url2, url3]
Generate a weekly SEO report
Run a full SEO health check and give me a grade
What are the top 5 things I should fix on my site right now?
Built-in SEO analysis beyond raw data
The server goes beyond raw data with a built-in analysis engine:
- CTR Benchmarks -- Compares your click-through rates against industry-average benchmarks by position. Flags pages that underperform and estimates how many additional clicks you could gain.
- Trend Detection -- Analyzes time-series data to detect upward, downward, or stable trends across your queries and pages.
- Query Classification -- Classifies queries by user intent (informational, investigational, transactional, navigational, problem-solving) and sub-type (how-to, comparison, review, error/fix, and more).
- Opportunity Scoring -- Scores every opportunity by traffic impact potential, factoring in impressions, CTR gap, position proximity, and volume.
- Recommendation Engine -- Generates specific, prioritized recommendations based on the data patterns found in your property.
What's not available through the API
The Google Search Console API has known limitations. The following data is not available through the API and therefore not provided by this server:
- Core Web Vitals -- Page experience and performance metrics
- Crawl Stats -- Crawl requests, response times, host status
- Manual Actions -- Penalties and security issues
- Links Report -- Internal and external link data
- Removals -- URL removal requests
- Rich Results -- Detailed rich result reports (basic info is available via URL Inspection)
These reports are only available in the Search Console web interface.
Using HTTP instead of stdio
For environments that prefer HTTP over stdio, start the server with the --http flag:
npx awesome-gsc-mcp --httpThe server listens on port 3000 by default. Override with the PORT environment variable:
PORT=8080 npx awesome-gsc-mcp --httpEndpoints:
| Path | Method | Description |
|---|---|---|
/mcp |
POST | MCP protocol endpoint (Streamable HTTP transport) |
/health |
GET | Health check -- returns {"status":"ok","auth":"..."} |
Common questions
How often does GSC data update?
Search Console data typically has a 2–3 day delay. For settled, final numbers pass dataState: 'final' in your search analytics queries. The most recent 2–3 days may still change as Google processes data.
What are the rate limits? The server has built-in rate limiting at 20 requests/second with a burst allowance of 30. The Google Search Console API also has its own daily quota — check your Google Cloud Console quotas page if you hit limits.
Can I work with multiple sites?
Yes. Use list_properties to see all accessible sites, then specify the siteUrl parameter in any tool to target a specific property.
How do domain properties work?
Domain properties use the sc-domain:example.com format. This covers all subdomains and protocols. URL-prefix properties use the full URL like https://www.example.com/.
What data is NOT available through the API? See the API Limitations section. Core Web Vitals, crawl stats, links, manual actions, and removals are only available in the Search Console web interface.
Build, test, and run locally
# Install dependencies
npm install
# Build
npm run build
# Run tests
npm test
# Development mode (watch + rebuild)
npm run dev
# Type check
npm run lint
# Start locally (stdio)
npm start
# Start locally (HTTP)
npm start -- --http