easygsc

Let your AI app (Claude, Codex, Gemini, Cursor, VS Code Copilot or any other MCP app) read your Google Search Console data and help you with SEO.

• Read-only. It can see your data, never change it.
• Small. 4 tools, ~1,600 lines of Python you can audit in one sitting.
• Private. Talks only to Google. No telemetry, no third-party servers.

Ask things like "Which queries get impressions but few clicks?" or "Is this page indexed?" and your AI pulls the real numbers from Search Console.

Setup (about 5 minutes)

You need:

• A Google account with access to at least one Search Console property.
• uv installed. It also installs Python for you if needed.
  • Windows: winget install astral-sh.uv
  • macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh

Step 1. Run the guided setup

uvx easygsc setup

It walks you through the Google Cloud steps one at a time, opening the right page in your browser and waiting for you to finish:

1. Create a project.
2. Enable the Search Console API.
3. Configure the consent screen (External).
4. Create a Desktop app OAuth client and download its JSON.
5. Fill in Branding with your website's links (no logo).
6. Publish the app.

Then it finds the JSON in your Downloads folder (or the OneDrive one, or asks for the path), checks it is a Desktop client, copies it to ~/.config/easygsc/client_secret.json with 0600 permissions, runs the Google login, checks that your properties are readable, and moves on to Step 2. It tells you which file it used and where it installed it.

• It never overwrites a different client file without asking, and only deletes your download if you say yes.
• No browser? Add --no-browser to print the URLs instead.
• Type q or press Ctrl+C at any prompt to stop; run uvx easygsc setup again to resume.

Step 2. Pick your AI apps

Setup ends with a numbered list of AI apps. The ones it finds on your computer are marked; press Enter to connect those, or type the numbers you want, like 1,3.

Then do what it says for each app (usually: restart it) and ask "List my Search Console sites."

• Your settings are safe. It only edits plain JSON files, saves a backup next to each one first (<file>.<date>.bak), keeps all your other settings, and asks before replacing an existing easygsc entry. A file it can't edit safely, such as one with comments, is left alone and you get the exact text to paste.
• Add an app later with easygsc connect (uvx easygsc connect).
• Browser-only chats (ChatGPT, claude.ai or Gemini on the web) can't start programs on your computer, so they can't use easygsc. Use their desktop or command-line app: Claude Desktop, Claude Code, Codex or Gemini CLI.

{
  "mcpServers": {
    "easygsc": {
      "command": "uvx",
      "args": ["easygsc@0.2.0"]
    }
  }
}

# as a plugin
claude plugin marketplace add diegomm27/easygsc
claude plugin install easygsc@easygsc

# or as a plain MCP server
claude mcp add easygsc -- uvx easygsc@0.2.0

CLI commands

mkdir $HOME\.config\easygsc -Force
Move-Item $HOME\Downloads\client_secret_*.json $HOME\.config\easygsc\client_secret.json

mkdir -p ~/.config/easygsc
mv ~/Downloads/client_secret_*.json ~/.config/easygsc/client_secret.json

uvx easygsc auth

uvx easygsc doctor

Try it

Start a new chat and ask:

• "List my Search Console properties."
• "Top 50 queries by impressions in the last 28 days for sc-domain:example.com."
• "Which pages have lots of impressions but a CTR under 2%?"
• "Queries where I rank between 5 and 15 on mobile."
• "Check the status of my sitemaps."
• "Is https://example.com/blog/post indexed?"

Start with the first one: it returns the exact property names (sc-domain:... or https://.../) the other tools need.

Tools

Data comes back unprocessed (TSV or Google's raw JSON), so Claude works with exact numbers.

Troubleshooting

To revoke access at any time: myaccount.google.com/permissions → easygsc → Remove access.

Security and transparency

• Permission requested: only https://www.googleapis.com/auth/webmasters.readonly. easygsc cannot submit sitemaps, edit properties or manage users.
• Network lock: every request goes through one guard (src/easygsc/allowlist.py) that only allows www.googleapis.com, searchconsole.googleapis.com, oauth2.googleapis.com and accounts.google.com. Anything else, redirects included, fails before it's sent.
• Endpoints used: sites.list, searchAnalytics.query, sitemaps.list, urlInspection.index.inspect. Nothing else.
• Files on disk: ~/.config/easygsc/client_secret.json (yours, installed by easygsc setup with 0600 permissions) and ~/.config/easygsc/token.json (your login, also 0600; best effort on Windows). Keep token.json private: whoever has it can read your Search Console.
• AI app settings: setup and connect only touch the apps you pick, back up each file first and make no network calls (src/easygsc/connect.py).
• Dependencies: mcp, google-auth, google-auth-oauthlib, pinned exactly. That's all.
• Not included on purpose: writes, analysis or scoring, telemetry, update checks, bundled prompts.

Development

git clone https://github.com/diegomm27/easygsc.git
cd easygsc
uv sync                      # install with dev dependencies
uv run pytest                # tests (no network, HTTP is mocked)
uv run ruff check src tests && uv run ruff format --check src tests
claude plugin validate .     # check the plugin manifest

CI runs lint and tests on Linux, macOS and Windows (Python 3.10 and 3.12). Releases are published to PyPI through Trusted Publishing.

License

MIT. See LICENSE.