google-search-console-mcp: Instructions file for Codex

AGENTS.md — Agent Operating Manual

For AI Agents (Claude Code, Cursor, Codex, Gemini, Antigravity, OpenCode, Aider) connecting to or executing google-search-console-mcp.

---

⚡ 1. Fast Install & Client Wiring (Start Here)

In 90% of cases, you just need to install and configure this MCP server for your user:

# 1-Line Universal Auto-Installer (Configures Claude Code, Cursor, Claude Desktop & Antigravity)
curl -fsSL "https://gsc.builditwithai.xyz/install" | bash

# Or launch directly via stdio:
uvx google-search-console-mcp
npx -y google-search-console-mcp

Client Config Snippet (mcp.json / claude_desktop_config.json)

{
  "mcpServers": {
    "google-search-console": {
      "command": "uvx",
      "args": ["google-search-console-mcp"],
      "env": {
        "GSC_SITE_URL": "https://example.com/",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service_account.json"
      }
    }
  }
}

---

📖 2. What This Repo Is

A production MCP server for Google Search Console (GSC). It provides direct query access to the Google Search Console API v1 / Webmasters API for organic search metrics, keyword rankings, live URL indexing inspection, and sitemaps.

Primary Tools Available:

• get_search_analytics: Query organic clicks, impressions, CTR, and average position grouped by query, page, country, device, and date.
• list_sites: List all verified properties accessible to the service account.
• inspect_url: Real-time URL indexing status, crawl issues, canonicalization, and mobile usability check.
• list_sitemaps, submit_sitemap, delete_sitemap: Manage XML sitemaps.
• skill_read / skills_list: Load built-in SEO diagnostic playbooks.

---

👤 3. How to Handle the Human (Auth & Setup)

If credentials are not yet configured, guide the human with these steps:

1. Ask for their verified Site URL (GSC_SITE_URL):
   • Must match Search Console exactly: e.g. https://example.com/ (URL-prefix) or sc-domain:example.com (Domain property).
2. Ask for a Google Cloud Service Account JSON Key:
   • The Service Account email must be added as a Full or Restricted user in Search Console → Settings → Users and permissions.
   • Once they have the JSON key file, set:

     export GSC_SITE_URL="https://example.com/"
     export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service_account.json"