geo-score

geo-score

Can AI engines cite your site? A free 0–100 score from one command. Do they? Check through their APIs with your own keys.

Score (free, no key) → Ask one question (your API keys) → Watch a question set every week (your API keys). Three levels, one tool · the citation half is never added to the score.

curl -sL https://raw.githubusercontent.com/jianruntech/geo-score/v1.8.2/cli/geo_score.py \
  | python3 - stripe.com --brief

One command. Every check, and what the next tier needs. The report says how long its run took.

  AIV READINESS  https://stripe.com
──────────────────────────────────────────────────────────────────────────
  72 / 100   Solid
  11 points to Leading

  Reachable 13/15
   ◐ Crawlers allowed in robots.txt   ███████████░░░░░░░  3/5
   ✓ Reachable to retrieval agents    ██████████████████  5/5
   ✓ Main content server-rendered     ██████████████████  5/5
  Understandable 17/22
   ◐ Sitemap discoverable and fresh   █████████░░░░░░░░░  2/4
   ✓ llms.txt present and structured  ██████████████████  5/5
   ✓ Organization + WebSite schema    ██████████████████  6/6
   ✗ BreadcrumbList on nested pages   ░░░░░░░░░░░░░░░░░░  0/3
   ✓ Page-type schema (Product, FAQ…) ██████████████████  4/4
  Content Citability 21/35
   ✓ Self-contained answer passages   ██████████████████  9/9
   ◐ Headings match how people ask    ████████░░░░░░░░░░  3/7
   ◐ Freshness signal present         █████████░░░░░░░░░  3/6
   ◐ Statistics carry a source        ████████░░░░░░░░░░  3/7
   ◐ Named, verifiable authorship     █████████░░░░░░░░░  3/6
  Brand Credibility 9/10
   ⊘ Third-party listings             ··················   —
   ⊘ Independent mentions             ··················   —
   ✓ Knowledge-graph entity           ██████████████████  4/4
   ✓ sameAs links resolve             ██████████████████  3/3
   ◐ Video and multimodal presence    ████████████░░░░░░  2/3
  Answer Fit 2/4
   ◐ Content shaped for extraction    █████████░░░░░░░░░  2/4
   ⊘ Covers the questions people ask  ··················   —
   ⊘ Chinese engine readiness         ··················   —
  ✓ full · ◐ partial · ✗ zero · ⊘ not measured (left the denominator)

  Biggest gaps
   +3 next tier (+3 to full)  Freshness signal present          needs: most pages do, and dateModified agrees with the visible date
   +3 next tier (+3 to full)  Named, verifiable authorship      needs: and the name links to a verifiable identity page
   +2 next tier (+2 to full)  Crawlers allowed in robots.txt    needs: mainstream retrieval user-agents explicitly allowed

  Scored 62 / 86 observable · 4 checks left the denominator · rubric v1.1 · took 91.5 s
  Needs off-site search or judgement: p3.listings, p3.mentions, p4.question-coverage
  Not observable this run: p4.cn-engines (not a Chinese-language site)

  Full rubric and what each tier means:
  https://github.com/jianruntech/geo-score/blob/v1.5.0/rubric/v1.1.md
  Score moved, or a check shows —? https://github.com/jianruntech/geo-score/blob/v1.5.0/guide/troubleshooting.md

geo_score.py stripe.com, recorded with geo-score 1.5.0 on 2026-10-03 through an HTTPS proxy (the footer's time includes it). The image above is an earlier run, with 1.1.0. From 1.7.0 the report also prints three observations under Outside the score after the checks (robots.txt rules page by page, links in the server HTML, hreflang), which never move the score; this recording predates them. See cli/README.md.

Python 3.8+, standard library only, nothing to install. It reads public URLs and prints a score against a published, versioned rubric — not a black box.

See how 324 well-known sites score → · a quarter of them are unreadable to AI crawlers.

GEO means Generative Engine Optimization — getting cited by ChatGPT, Perplexity, Google AI Overviews, Gemini and Copilot. Nothing to do with geography or maps.

Contents: MCP server · Three levels · What it checks · Leaderboard · Ways to run it · Does AI cite you? · Scope · How accurate is it? · Install and stability · Repository layout · Contributing

---

MCP server

geo-score-mcp is a local MCP server (stdio, Python standard library only). It gives an agent the same three levels as the CLI: score a site for free, ask the AI engines one question, and track a question set week over week.

The buttons and the lines below run geo-score 1.8.2 from PyPI with uvx, which needs only uv: no git and no build step. They add no keys of their own, but a server started from a shell that exports a provider key (Claude Code passes its environment on) can use it. For a server that cannot spend, add --read-only after mcp.

Claude Code

claude mcp add --scope user geo-score -- uvx geo-score@1.8.2 mcp

Standard config (no keys in the file) for any client that reads an mcpServers file:

{
  "mcpServers": {
    "geo-score": {
      "command": "uvx",
      "args": ["geo-score@1.8.2", "mcp"]
    }
  }
}

Claude Desktop does not read your shell's PATH: put the full path that which uvx prints in command.

Without access to PyPI, the release wheel: uvx --from https://github.com/jianruntech/geo-score/releases/download/v1.8.2/geo_score-1.8.2-py3-none-any.whl geo-score-mcp

From source (needs git): uvx --from git+https://github.com/jianruntech/geo-score@v1.8.2 geo-score-mcp

Tool	Level	Cost	Writes	Hints	Args
score_site	1	Free	No	read-only, open-world	url, urls, sample
ask	2	Paid (your keys)	No	non-destructive, open-world	question, engines, brand, domains
run	3	Paid (your keys); dry_run is free	A run file under .geo-score/watch/runs/, next to the config	non-destructive, open-world	dry_run, engines, limit, max_calls, budget_usd
list_runs	3	Free	No	read-only, idempotent	—
report	3	Free	No	read-only, idempotent	run, since, format
diff	3	Free	No	read-only, idempotent	from, to, format
status	—	Free	No	read-only, idempotent	—

Resources: geo-score://rubric/v1.1.

Prompts: audit_site (url), check_citations (question, brand), weekly_watch, compare_runs (from, to), explain_check (check_id).

Bold arguments are required. Hints are the tools' MCP annotations: clients may use them to decide what to confirm, and they are hints, not guarantees. Only ask and run can spend money, and only with the provider keys you give the server.

Things to ask your agent:

Prompt	What it calls
Score https://acme.com for AI-search readiness and list the 3 checks with the most points to gain.	score_site with url
Dry-run my tracked questions and tell me the planned calls and caps.	run with dry_run: true (level 3, needs a config)
Compare my last two watch runs: which engines changed, and is any change outside the noise?	diff (defaults to the latest two runs)

Keys and config. score_site needs no key. ask and run read the provider keys (OPENAI_API_KEY, PERPLEXITY_API_KEY, GEMINI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY) from the server's environment, which is not your terminal's: a desktop app does not see what you exported in a shell. The level 3 tools also need a geo-score-watch.json. Pass it as -c /absolute/path/geo-score-watch.json, because a GUI client does not start the server in your project. From 1.4.0, --read-only gives a server that cannot spend anything.

Setup for each client (Claude Code, Claude Desktop, Codex, Cursor, VS Code, Gemini CLI, Devin Desktop, Zed), the Claude Code plugin, timeouts, security and troubleshooting: guide/mcp.md.

Three levels, one tool

Level	What it answers	Needs	Command
1 · Score	Can AI engines reach, parse, trust and cite the site? 0–100 against the open rubric	Nothing: no key, no install	geo_score.py stripe.com
2 · Ask	Right now, for a question you care about, do they cite it?	An API key for any of OpenAI, Perplexity, Gemini, Anthropic, OpenRouter	geo_score.py stripe.com --ask "best payments API for marketplaces"
3 · Watch	How often are you cited, against which competitors and sources, week over week?	Your API keys and a fixed question list	geo_score.py watch run

Level 1 is the score. Levels 2 and 3 measure the outcome the rubric keeps out of the score on