geoseo-mcp

Run a Google search via SerpAPI and parse the AI Overview block. Returns ``aio_present``, the AIO answer text, the URLs/domains AIO cites, and the top-10 organic results for context. Use this to track which pages Google's generative answers actually source.

For a batch of queries, report AIO fire-rate and citation share for ``target_domain``. This is the GEO companion to ``multi_llm_citation_check`` — same idea, but specifically for Google's on-SERP AI Overviews. Run weekly and snapshot to ``snapshot_serp_aio`` to track AIO visibility over time.

Audit a single page (local file path or http(s) URL). Set ``render=True`` to audit the page after JavaScript runs (needs the optional ``geoseo-mcp[render]`` extra + ``playwright install chromium``). Either way the report flags pages that are empty without JavaScript, since most AI crawlers don't execute it. Returns a structured report with: title/meta/headings, word count, link counts, image alt coverage, JSON-LD schema types, Open Graph, Twitter Card, freshness signals, GEO-quotability score, and a list of human-readable findings. Plus a 0-100 overall ``score``. Examples: ``audit_page("seo/aa-meetings-what-to-expect.html")`` ``audit_page("https://soberpath.com/blog/quit-drinking")``

Recursively audit every HTML file under a folder. Returns per-file scores, an aggregate summary (mean score, worst pages, most common findings), and the top opportunities for improvement. Useful as the first call against a content directory to spot the worst offenders quickly.

Crawl errors / blocked URLs / DNS issues reported by Bingbot.

List all Bing-verified sites for the API key owner.

Per-page stats from Bing Webmaster.

Last-6-months query stats from Bing Webmaster (clicks, impressions, position). ``site_url`` must match what Bing has verified, e.g. ``https://example.com/``.

Submit a URL for fast crawling. Daily quota applies (default ~10/day).

Index status + crawl info for a single URL on Bing.

Ask Brave's AI Answers (grounded in Brave Search); return answer + cited URLs. Brave runs its own independent web index, so it is a useful extra signal next to Google/Bing-backed engines. Requires the Brave Answers plan (``GEOSEO_BRAVE_API_KEY``).

Ask Claude (with server-side web search) a question; return answer + cited URLs.

Find dead, redirected, or flaky outbound links across a folder of HTML. Every external ``<a href>`` is collected (``mailto:``, ``tel:``, ``javascript:`` and in-page anchors are skipped) and each unique URL is checked once with HEAD, falling back to GET for servers that refuse HEAD. Results are grouped as ``ok`` / ``redirect`` / ``client_error`` / ``server_error`` / ``timeout`` / ``dns_fail`` / ``error``, and every non-ok link lists the pages it appears on plus a suggested action. ``site_host`` (e.g. ``"example.com"``) marks absolute links to your own site as internal so they're skipped. Results are cached locally for ``cache_days`` (set 0 to force a fresh check); timeouts are never cached.

Ask Gemini (with Google Search grounding) a question; return answer + cited URLs. Grounding sources here are the same signal Google uses for AI Overviews, so this is the closest open-API proxy for "what AIO might cite for this query".

Generate a draft ``llms.txt`` from a folder of HTML pages. ``llms.txt`` (https://llmstxt.org) is the emerging standard for telling LLM crawlers where your canonical content lives. This tool reads each page's ``<title>`` and meta description, groups by URL prefix, and produces spec-compliant Markdown ready to drop at ``/llms.txt``. ``section_strategy`` controls grouping: - ``first_path_segment`` (default): groups by first URL path segment, e.g. all ``/blog/...`` pages under "Blog". - ``flat``: a single "Pages" section.

Report which engines are configured and reachable. Always safe to call. Returns a dict keyed by engine name with `configured: bool` and a short message. Use this as the first call in a session to know what's available.

Ask Grok (with live web search) a question; return answer + cited URLs. Uses the xAI Responses API with the ``web_search`` tool. ``citations`` are the URLs Grok actually cites inline; ``sources_considered`` lists everything it looked at. Set ``x_search=True`` to also search X posts. Default model: ``GEOSEO_GROK_MODEL`` (``grok-4.3``).

Get index status for a specific URL via the URL Inspection API. Returns coverage state, last crawl time, mobile usability, indexed verdict, and indexing rich-result data. Slow (~1s/call); rate-limited by Google.

List all Search Console properties the authenticated user can access. Returns a list of site entries with ``siteUrl`` and ``permissionLevel``. Use ``siteUrl`` from this list as input to other ``gsc_*`` tools.

Query GSC search analytics.

Submit (or resubmit) a sitemap URL to GSC. ``feedpath`` is the absolute URL of the sitemap, e.g. ``https://example.com/sitemap.xml``.

Notify Bing, Yandex, Naver, Seznam, and Yep that a single URL was published or updated. Requires ``GEOSEO_INDEXNOW_KEY`` env var (a 32-char hex string you also host at ``https://yourdomain.com/<key>.txt``).

Batch-notify search engines about up to 10,000 URLs (must share one host). Best for sitemap-wide rebuilds or large content updates.

Audit a folder of HTML pages as a directed internal-link graph. Returns counts of files/edges, the orphans (no inbound links), dead-ends (no outbound links), top hub pages, and a list of dangling internal hrefs that don't resolve to any file. Pass ``site_host`` (e.g. ``"example.com"``) if pages link to themselves with absolute URLs — those will then count as internal edges. Files are also matched by URL slug, so ``/blog/foo`` resolves to ``foo.html`` even when paths don't match exactly.

Validate a page's JSON-LD against Google's structured-data requirements. ``source`` is a local HTML file or an http(s) URL. Every ``application/ld+json`` block is parsed (``@graph`` included) and each typed entity is checked against Google's documented required and recommended properties for Article, Product (with nested Offer / AggregateRating / Review), Recipe, LocalBusiness, BreadcrumbList, Event, VideoObject, SoftwareApplication, JobPosting, QAPage, Review and Organization. FAQPage and HowTo are checked against schema.org since Google no longer shows those rich results. Returns per-entity ``{type, ok, required_missing, recommended_missing, line_estimate, doc}``. ``ok`` is false when a required property is missing or the JSON is invalid.

Run ``lint_schema_page`` over every HTML file in a folder. Returns files with errors, files that have no JSON-LD at all, a count of schema types found, the most common missing required properties, and per-file problems.

Return the LLM engines currently configured (have an API key).

How often each configured LLM cites (or mentions) ``target_domain``. The headline GEO/AEO tool. Feed it your top 20-50 buyer questions and get a per-engine breakdown for ChatGPT/Claude/Gemini/Perplexity/Grok/Brave: - ``citation_rate`` (+ 95% interval): share of answers linking to your domain or any subdomain of it. - ``mention_rate`` / ``unlinked_mention_rate``: answers that name your brand, with or without a link. Pass ``brand_aliases`` (e.g. ``["Acme", "Acme CRM"]``) if your brand isn't obvious from the domain. - ``top_competing_domains`` and per-question results. LLM answers vary run to run, so every question is asked ``samples`` times per engine (default ``GEOSEO_CITATION_SAMPLES``, 3; max 10). Cost scales with questions x samples x engines.

Ask the same question to all (or selected) configured LLM engines in parallel. ``engines``: optional subset of ``["perplexity","openai","anthropic","gemini","grok","brave"]``. Default: every engine with credentials configured (see ``geoseo_status``). Engines that error are reported per-engine and don't block the others.

Ask ChatGPT (with web search) a question; return answer + cited URLs. Uses the OpenAI Responses API with the ``web_search`` tool. Default model: ``GEOSEO_OPENAI_MODEL`` (``gpt-5-mini``).

Citation share for ``target_domain`` across a Perplexity question batch.

Ask Perplexity (Agent API + web search); return answer + cited URLs/domains. Defaults to the ``fast`` effort preset. Pass ``model`` to pin one (e.g. ``openai/gpt-5-mini``); legacy names like ``sonar`` still work.

Run a GSC performance query and persist the rows as a snapshot. Run this on a schedule (cron, n8n, ``launchd`` — anything that can invoke an MCP tool) to build a local time-series of search performance. Default dimensions: ``["query"]``.

Run multi-LLM citation check and persist the per-question results. Builds the dataset behind ``trend_llm_citations``. ``engines`` defaults to every configured LLM (see ``geoseo_status``). With ``samples > 1`` a question is stored as cited when most samples cite you.

Run AIO citation check via SerpAPI and persist as ``serpapi_aio`` engine rows.

Suggest top-K internal links to add to each page in a folder. By default uses TF-IDF cosine similarity over ``<title>``, headings, meta description and body text (offline, free). Set ``mode`` to ``"openai"`` (text-embedding-3-small), ``"gemini"`` (gemini-embedding-001) or ``"local"`` (sentence-transformers) for embedding similarity; ``model`` overrides the default model. Vectors are cached in SQLite by content hash, so re-runs are cheap. Excludes links the source already has, plus the page itself. Returns suggestions for ``page`` only if provided, otherwise for every page. Each suggestion includes a cheap ``anchor_hint`` derived from terms shared between source headings and target title.

Time-series of clicks/impressions/position from stored GSC snapshots. Aggregates by ``captured_at``. Filter by ``query`` and/or ``page`` to drill in. Returns up to ``limit`` most recent snapshots in chronological order.

Create the local SQLite snapshot DB if it doesn't exist; return its path.

Per-snapshot citation share for ``target_domain`` over time. ``engine`` filters to one of ``perplexity|openai|anthropic|gemini|serpapi_aio``. Returns rows of ``{captured_at, engine, questions, cited, citation_share}``.

Inventory of what's stored: row counts, sites/domains, oldest/newest snapshots.

Validate an ``llms.txt`` file (local path or URL) against the spec. Returns parsed structure plus an ``issues`` list with line numbers for any violations (missing H1, broken link syntax, non-http(s) URLs, etc).

Active Yandex site diagnostics (by severity) plus sample broken internal links.

List sites in the token owner's Yandex Webmaster account.

Top Yandex search queries: shows, clicks, average show/click position. ``order_by``: ``TOTAL_SHOWS`` or ``TOTAL_CLICKS``. ``device``: ``ALL``, ``DESKTOP``, ``MOBILE_AND_TABLET``, ``MOBILE``, ``TABLET``. Dates are ``YYYY-MM-DD``; defaults to the last week.

Site quality index (SQI), pages in search, excluded pages, problem counts. ``site`` can be a URL (``https://example.com/``) or a Yandex host id (``https:example.com:443``).

Queue a URL for Yandex recrawl. Daily quota applies.

Indexing + search status for a URL in Yandex "Monitoring important pages".