Sam GSC MCP
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| MCP_HOST | No | Bind address for HTTP/SSE transports. | 127.0.0.1 |
| MCP_PATH | No | Endpoint path for streamable HTTP. | /mcp |
| MCP_PORT | No | Port for HTTP/SSE transports. | 3001 |
| GSC_USE_ADC | No | Set to true to allow Application Default Credentials in auto mode. | false |
| GSC_SITE_URL | No | Default Search Console property when a tool is called without site_url. | |
| GSC_TOOLSETS | No | Comma list of tool groups to load: setup, reference, skills, properties, analytics, insights, inspection, indexing, sitemaps. | all |
| GSC_AUTH_MODE | No | Authentication mode: auto (OAuth -> service account -> ADC), oauth, service_account or adc. | auto |
| GSC_LOG_LEVEL | No | Server log level written to stderr. | WARNING |
| GSC_READ_ONLY | No | Set to true for read-only OAuth scope and to hide every write tool. | false |
| MCP_TRANSPORT | No | Transport: stdio, sse or streamable-http (http is an alias). | stdio |
| GSC_CONFIG_DIR | No | Directory where token.json and config.json live. Defaults to the OS config folder. | |
| GSC_DATA_STATE | No | Data state: all matches the Search Console dashboard; final uses confirmed data only. | all |
| GSC_EXPORT_DIR | No | CSV export folder. | ~/Documents/sam-gsc-exports |
| GSC_OAUTH_PORT | No | Local port for the OAuth redirect. 0 uses a random port. | 0 |
| GSC_SKIP_OAUTH | No | Set to true to force service-account auth (same as GSC_AUTH_MODE=service_account). | false |
| GSC_TOKEN_FILE | No | OAuth token location. Defaults to <config dir>/token.json. | |
| GSC_API_RETRIES | No | Automatic retries on 429/5xx responses. | 3 |
| GSC_UPDATE_CHECK | No | Set to false to stop check_for_updates from calling GitHub. | true |
| GSC_OAUTH_TIMEOUT | No | Seconds to wait for browser sign-in. | 300 |
| GSC_COMPAT_ALIASES | No | Set to true to register alternative compatibility tool names. | false |
| GSC_DISABLED_TOOLS | No | Comma list of individual tools to hide. | |
| GSC_MAX_BATCH_URLS | No | Maximum URLs per inspection batch (1-100). | 10 |
| GSC_CREDENTIALS_PATH | No | Path to a service account JSON key. GOOGLE_APPLICATION_CREDENTIALS is accepted too. | |
| GSC_ALLOW_DESTRUCTIVE | No | Set to true to enable add_site, delete_site, delete_sitemap and URL_DELETED notifications. | false |
| GSC_ENABLE_INDEXING_API | No | Set to true to add the Indexing API scope and indexing tools. | false |
| GSC_INSPECTION_CONCURRENCY | No | Parallel URL inspections (1-20). | 10 |
| GSC_OAUTH_CLIENT_SECRETS_FILE | No | Path to your OAuth Desktop app client JSON. Required for OAuth with uvx. | |
| GOOGLE_APPLICATION_CREDENTIALS | No | Path to a Google service account JSON key, accepted as an alternative to GSC_CREDENTIALS_PATH. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| get_capabilitiesA | List every tool by category, the current auth status and active settings. Call this FIRST when unsure what the server can do or when something fails. |
| setup_gsc_accessA | Configure or repair Google Search Console access in-chat, without editing config files or restarting. Pass the values directly, or call with no arguments and the server will ask you for them (when your client supports interactive prompts). Only file PATHS are stored — never key contents. Args: auth_method: 'oauth' or 'service_account' (auto-detected from the file if omitted) credentials_path: Absolute path to a service account JSON key oauth_client_secrets_file: Absolute path to an OAuth 'Desktop app' client JSON site_url: Optional default property used when tools are called without site_url save: Save these paths to the server's config.json so they survive restarts (default true) |
| reauthenticateA | Sign out and open the Google sign-in page again — use it to log in the first time, fix expired tokens or switch Google accounts (OAuth only). |
| check_for_updatesA | Check GitHub for a newer version of Sam GSC MCP and show the upgrade command. |
| get_creator_infoB | About Krishanth Sam, who built Sam GSC MCP. |
| list_available_dimensionsA | List every Search Analytics dimension (query, page, country, device, date, searchAppearance, hour) with what it means. |
| list_available_metricsA | List the four Search Analytics metrics (clicks, impressions, ctr, position) and their units. |
| list_filter_optionsC | Valid filter operators, search types, device values, common search appearances, data states and example filters. |
| skills_listA | List the bundled SEO playbooks (weekly report, cannibalization, indexing audit, content opportunities, brand visibility, traffic-drop diagnosis and more). Read one with skill_read. |
| skill_readA | Return the full step-by-step playbook for one skill. Args: skill_id: Skill id from skills_list, e.g. "seo-weekly-report" or "keyword-cannibalization" |
| list_propertiesA | List all Google Search Console properties (sites) you can access, with permission level. Call this first to get the exact site_url for other tools. |
| get_site_detailsA | Permission level and verification/ownership details for one property. Args: site_url: Exact property from list_properties ("https://example.com/" or "sc-domain:example.com"). Defaults to GSC_SITE_URL. |
| add_siteA | Add a property to your Search Console account (requires GSC_ALLOW_DESTRUCTIVE=true). You still need to verify ownership in Search Console. Args: site_url: e.g. "https://www.example.com/" (URL-prefix) or "sc-domain:example.com" (domain) |
| delete_siteA | Remove a property from your Search Console account (requires GSC_ALLOW_DESTRUCTIVE=true). Args: site_url: Exact property string from list_properties |
| get_search_analyticsA | Top queries/pages/countries/devices/dates with clicks, impressions, CTR (%) and position. Args: site_url: Exact property from list_properties. Defaults to GSC_SITE_URL. "example.com" is auto-matched. days: Days to look back (default 28). Ignored when start_date is given. dimensions: "query", "page", "country", "device", "date", "searchAppearance", "hour" — comma list or array, e.g. "query,page" row_limit: Rows to return (default 20, up to 25000). Use get_advanced_search_analytics or export_search_analytics for big pulls. start_date: YYYY-MM-DD (optional) end_date: YYYY-MM-DD (optional, defaults to the latest available day) search_type: web, image, video, news, discover, googleNews filters: AND-combined list, e.g. [{"dimension":"country","operator":"equals","expression":"ind"}] summary_only: True returns only totals (cheapest call) data_state: "all" (matches dashboard, default) or "final" (confirmed data only) intent: Optional one-line note of what you're trying to learn (echoed back for context) |
| get_advanced_search_analyticsA | Power query: up to 25,000 rows per call with pagination, sorting, regex and multi-filter AND logic. Args:
site_url: Exact property from list_properties (defaults to GSC_SITE_URL)
start_date: YYYY-MM-DD (defaults to |
| get_performance_overviewB | Site totals (clicks, impressions, CTR, position) plus the day-by-day trend. Args: site_url: Exact property (defaults to GSC_SITE_URL) days: Days to look back (default 28) search_type: web, image, video, news, discover, googleNews |
| get_site_summaryA | Headline summary: this period vs the previous period of the same length, with % changes and daily data. Args: site_url: Exact property (defaults to GSC_SITE_URL) period_days: Length of each period in days (default 28) search_type: web, image, video, news, discover, googleNews |
| compare_search_periodsA | Compare two date ranges item by item (queries, pages...). Period 1 = the period you analyse, Period 2 = the baseline. Positive deltas mean Period 1 did better (more clicks/impressions, higher CTR, better/lower position). With no dates it compares the last 28 days against the 28 days before. Args: site_url: Exact property (defaults to GSC_SITE_URL) period1_start: Analysed period start YYYY-MM-DD period1_end: Analysed period end YYYY-MM-DD period2_start: Baseline start YYYY-MM-DD period2_end: Baseline end YYYY-MM-DD dimensions: Group by, e.g. "query" or "page" or "query,page" limit: Number of biggest movers to return (default 20) search_type: web, image, video, news, discover, googleNews filters: Optional AND filters applied to both periods |
| get_search_by_page_queryA | Search queries that bring traffic to one specific page. Args: site_url: Exact property (defaults to GSC_SITE_URL) page_url: Full URL of the page (exact match) days: Days to look back (default 28) row_limit: Rows to return (default 20, up to 25000) search_type: web, image, video, news |
| get_hourly_performanceA | Hour-by-hour clicks and impressions for roughly the last 10 days (great for launches, news spikes and outage checks). Hourly data can be partial. Args: site_url: Exact property (defaults to GSC_SITE_URL) days: Days of hourly data, 1-10 (default 3) filters: Optional AND filters, e.g. a page or query filter search_type: web, image, video, news, discover, googleNews |
| export_search_analyticsA | Bulk-export Search Analytics rows (auto-paginated, up to 500,000) to a CSV file on this computer and return its path plus a preview. Args: site_url: Exact property (defaults to GSC_SITE_URL) dimensions: e.g. "query,page" or "date,page,device" days: Look-back window when start_date is omitted (default 90) start_date: YYYY-MM-DD (optional) end_date: YYYY-MM-DD (optional) search_type: web, image, video, news, discover, googleNews filters: Optional AND filters max_rows: Safety cap (default 100000, max 500000) file_name: Optional file name; saved in GSC_EXPORT_DIR (default ~/Documents/sam-gsc-exports) |
| find_striking_distance_keywordsA | Quick wins: queries ranking just off the top spots (default positions 4-20) with real impressions, ranked by estimated extra clicks if they reached position 3. Args: site_url: Exact property (defaults to GSC_SITE_URL) days: Days to analyse (default 28) min_position: Lowest position to include (default 4) max_position: Highest position to include (default 20) min_impressions: Ignore rows below this (default 50) limit: Rows to return (default 30) |
| find_keyword_cannibalizationA | Find queries where two or more of your pages compete, with a suggested primary page and fix for each. Args: site_url: Exact property (defaults to GSC_SITE_URL) days: Days to analyse (default 28) min_impressions: Minimum impressions for a page to count on a query (default 20) min_share: A competing page must hold at least this % of the query's impressions (default 10) limit: Number of conflicts to return (default 20) |
| get_brand_vs_nonbrandA | Split traffic into branded vs non-branded queries: share of clicks/impressions, CTR, position and top queries for each. Args: site_url: Exact property (defaults to GSC_SITE_URL) brand_terms: Brand name plus variants/misspellings, comma separated, e.g. "acme,acme corp,akme" days: Days to analyse (default 28) top_n: Top queries to list per segment (default 10) |
| find_low_ctr_opportunitiesA | Pages that rank on top (default position <= 5) but get few clicks (CTR <= 2%): title/meta rewrites, or answers being shown in AI Overviews / featured snippets. Args: site_url: Exact property (defaults to GSC_SITE_URL) days: Days to analyse (default 28) max_position: Only rows at or above this position (default 5) max_ctr: CTR threshold in percent (default 2.0) min_impressions: Ignore rows below this (default 100) limit: Rows to return (default 30) |
| inspect_url_enhancedA | Full URL Inspection: index verdict, coverage, last crawl, canonicals, robots, fetch state, rich results (with issues), mobile usability and AMP. Args: site_url: Exact property (defaults to GSC_SITE_URL) page_url: Full URL to inspect (must belong to the property) language_code: Optional language for issue messages, e.g. "en-US" include_raw: Also return Google's raw response (default false) |
| check_url_statusA | Quick yes/no: is this URL indexed? Plus coverage state, last crawl, canonical and robots/fetch status. Args: site_url: Exact property (defaults to GSC_SITE_URL) page_url: Full URL to check |
| batch_url_inspectionA | Inspect several URLs at once (concurrently). Returns index verdict, coverage, last crawl and rich results per URL. Args: site_url: Exact property (defaults to GSC_SITE_URL) urls: URLs, one per line or a JSON array (default max 10, see GSC_MAX_BATCH_URLS) |
| check_indexing_issuesA | Check several URLs and group them into issue buckets: not indexed, canonical mismatch, robots blocked, noindex, fetch errors, rich-result issues. Args: site_url: Exact property (defaults to GSC_SITE_URL) urls: URLs, one per line or a JSON array |
| get_index_coverageA | Coverage report built from live URL Inspection: groups URLs by Google's coverage state with counts and example URLs. The public API has no bulk coverage endpoint, so this samples URLs from your top pages, a sitemap, or a list you give. Args: site_url: Exact property (defaults to GSC_SITE_URL) source: "top_pages" (pages with impressions, default) or "sitemap" urls: Optional explicit URLs (overrides source) sitemap_url: Sitemap to read when source="sitemap" (defaults to the first submitted sitemap) limit: How many URLs to inspect (default 20, max GSC_MAX_BATCH_URLS x 5) days: Window for picking top pages (default 28) issue_filter: Only return states containing this text, e.g. "crawled" or "duplicate" |
| get_mobile_issuesA | Mobile signals per URL from URL Inspection: crawled-as (smartphone/desktop), fetch state and any mobile-usability verdict/issues Google still returns. Note: Google retired the Mobile Usability report in Dec 2023, so the usability verdict is often empty; use Lighthouse/PageSpeed for layout checks. Args: site_url: Exact property (defaults to GSC_SITE_URL) urls: Optional URLs (one per line). Defaults to your top pages. source: "top_pages" or "sitemap" when urls is empty limit: URLs to check (default 10) issue_filter: Only return URLs whose issue types contain this text |
| get_sitemapsB | All submitted sitemaps with status, last download, errors/warnings and submitted URL counts by type. Args: site_url: Exact property (defaults to GSC_SITE_URL) |
| list_sitemaps_enhancedB | Detailed sitemap list, optionally the children of one sitemap index, with pending counts. Args: site_url: Exact property (defaults to GSC_SITE_URL) sitemap_index: Optional sitemap index URL to list its child sitemaps |
| get_sitemap_detailsA | Details for one sitemap: type, processing status, last submitted/downloaded, errors, warnings and content breakdown. Args: site_url: Exact property (defaults to GSC_SITE_URL) sitemap_url: Full sitemap URL |
| submit_sitemapA | Submit a new sitemap or resubmit an existing one. Args: site_url: Exact property (defaults to GSC_SITE_URL) sitemap_url: Full sitemap URL, e.g. https://example.com/sitemap.xml |
| delete_sitemapA | Remove (unsubmit) a sitemap from Search Console (requires GSC_ALLOW_DESTRUCTIVE=true). Already-indexed URLs stay indexed. Args: site_url: Exact property (defaults to GSC_SITE_URL) sitemap_url: Full sitemap URL |
| manage_sitemapsA | All-in-one sitemap tool: action = list, details, submit or delete. Args: site_url: Exact property (defaults to GSC_SITE_URL) action: list, details, submit or delete sitemap_url: Needed for details, submit and delete sitemap_index: Optional index URL for action=list |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| seo-weekly-report | 28-day performance snapshot, period-over-period changes, alerts and top queries. |
| content-opportunities | Striking-distance queries, low-CTR pages and content gaps worth acting on. |
| cannibalization-check | Queries where several of your pages compete, with a fix for each. |
| indexing-audit | Inspect your most visible pages and get a prioritised fix list. |
| analyze-brand-visibility | Branded vs non-branded share, CTR and positions. |
| diagnose-traffic-drop | Localise a search traffic drop: when, which segment, and the likely cause. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| skill-brand-visibility | Compare branded vs non-branded search performance to see whether people search for you by name (a destination) or only find you through generic queries (a reference). Use for brand share, branded traffic, brand awareness or non-brand growth questions. |
| skill-citation-opportunities | Find pages that rank at the very top but earn few clicks — often because Google answers on the results page via AI Overviews or featured snippets — and suggest ways to win the click. Use for AI Overview impact, zero-click searches or "high rank, low clicks" questions. |
| skill-content-decay | Find pages that are steadily losing clicks compared with earlier periods and pick the best candidates to refresh or update. Use for content refresh, decaying pages, old blog posts or "which pages should I update" questions. |
| skill-content-opportunities | Find quick-win content optimisation targets — striking-distance queries (positions 4-20), high-impression low-CTR pages and content gaps. Use when asked for content ideas, quick wins, low-hanging fruit or optimisation opportunities. |
| skill-diagnose-traffic-drop | Find when a Google search traffic drop started, which segment lost traffic (queries, pages, device, country, rich results) and the most likely cause (indexing, rankings or SERP changes). Use when traffic, clicks or impressions fell. |
| skill-indexing-audit | Audit whether Google has indexed your most important pages and produce a prioritised fix list. Use when asked about crawling, indexing problems, "is my page indexed", canonical issues, noindex or robots.txt blocks. |
| skill-intent-efficiency | Split search traffic by user intent — informational, commercial, transactional and navigational — to see which stage of the buyer journey brings clicks and where CTR is weak. Use for funnel, intent mix or "what kind of searches bring us traffic" questions. |
| skill-intent-segmentation | Segment queries into short keyword "searchers" and long conversational "prompters" (AI-style questions) to see whether your audience is shifting to natural-language search. Use for AI search behaviour, long-tail or conversational query analysis. |
| skill-keyword-cannibalization | Detect keyword cannibalization — queries where two or more of your pages compete for the same rankings — and recommend which page to keep. Use when asked about competing pages, keyword overlap, duplicate intent or cannibalization. |
| skill-search-appearance-audit | Audit which rich results and SERP features (video, review snippets, FAQ, product, AMP...) your site appears with, how they perform, and which queries likely trigger them. Use for rich results, structured data impact or SERP feature questions. |
| skill-seo-weekly-report | Build a complete weekly or monthly SEO performance report from Google Search Console. Use when asked for a site summary, performance overview, weekly/monthly report or "how is my site doing". |
| gsc-reference | Dimensions, metrics, operators and search types |
TDQS
Scored across 38 tools
Several clusters of near-duplicate tools make selection risky: manage_sitemaps (action=list/details/submit/delete) fully overlaps get_sitemaps, list_sitemaps_enhanced, get_sitemap_details, submit_sitemap and delete_sitemap; check_indexing_issues, batch_url_inspection and get_index_coverage all group URLs into issue buckets; and get_site_summary, get_performance_overview, get_search_analytics and compare_search_periods all answer 'how did traffic do'. check_url_status vs inspect_url_enhanced and get_search_analytics vs get_advanced_search_analytics are defensible tiering, but the sitemap and indexing clusters have no clear boundary.
The vast majority of names follow a clear verb_noun snake_case pattern (get_, list_, check_, find_, inspect_, submit_, delete_, compare_, export_). The main deviations are the documentation tools skills_list/skill_read, which invert to noun_verb and mix plural/singular, plus the bare reauthenticate.
38 tools for one API surface (Search Console) is heavy, and a large fraction are redundant: roughly six sitemap tools, three indexing-audit tools, four analytics query tools, and meta tools like get_creator_info, check_for_updates and get_capabilities. Consolidation could cut this to about 20 without losing capability.
The lifecycle is well covered: properties (list/get/add/delete), sitemaps (list/details/submit/delete), search analytics (basic, advanced, export, hourly, period comparison), URL inspection (single, quick, batch) plus setup/auth/skills helpers. Minor gaps only, such as no indexing-request workflow and no sitemap-index submission path distinct from submit_sitemap.