io.github.Rachit8484Published by GitHub account Rachit8484v0.4.0Updated Nov 6, 2026
SEO + GEO: Search Console, Bing, Yandex, IndexNow, AI Overviews and LLM citation tracking.
SEO and GEO toolkit: Search Console, Bing and Yandex data, IndexNow submission, AI Overview checks, and LLM citation tracking across six engines.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Follow the launch instructions in the repository.
An open-source MCP server for traditional SEO and Generative Engine Optimization (GEO): Google Search Console, Bing, IndexNow, Google AI Overviews, and citation tracking across ChatGPT, Claude, Gemini, Perplexity, Grok and Brave, all in one server.
[PyPI] [CI] [License: MIT] [Python 3.11+] [MCP]
Sample output:
Other keyless commands: audit-site ./content, generate-llms-txt ./content https://yourdomain.com, status. Run uvx geoseo-mcp --help for everything.
Poke at all 47 tools in the MCP Inspector:
Running geoseo-mcp with no arguments starts the MCP server over stdio, which is what MCP clients expect.
Or add it to ~/.cursor/mcp.json by hand (see examples/cursor-mcp.json).
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
Every key is optional; drop the ones you don't have. Other clients (Continue, Cline, Windsurf, VS Code) take the same command / args / env block. See examples/.
Then just ask:
"Which of ChatGPT, Claude, Gemini, Perplexity and Grok cite acme.com for 'best CRM for startups'? Run 3 samples each." "Audit my
./contentfolder and show the 5 worst pages." "Build the internal link graph and find orphan pages."
MIT licensed and local-first: your credentials and data stay on your machine.
multi_llm_citation_check(questions, target_domain) asks every configured engine each question several times (samples, default 3), because LLM answers vary from run to run. For each engine you get:
citation_rate with a 95% Wilson interval, plus a per-question cited_rate and a stable flagmention_rate and unlinked_mention_rate: answers that name your brand without linking to youtop_competing_domains: who gets cited instead of youdocs.acme.com counts for acme.com)Brand aliases are derived from the domain (acme.com → acme) and you can pass your own via brand_aliases. Requests run in parallel up to GEOSEO_MAX_CONCURRENCY (default 8).
Approximate list prices as of October 2026; check each provider's pricing page before running large batches.
A 10-question check with 3 samples across four engines is 120 calls, which is usually well under $2. Use samples=1 for quick spot checks.
web_search tool. Override the model with GEOSEO_OPENAI_MODEL.fast preset; set GEOSEO_PERPLEXITY_EFFORT or GEOSEO_PERPLEXITY_MODEL to change it.GEOSEO_XAI_API_KEY. Uses the Responses API with the web_search tool; override the model (default grok-4.3) with GEOSEO_GROK_MODEL.GEOSEO_BRAVE_API_KEY. Answers come from Brave's own index.docs/setup-gsc.md. One-time OAuth flow.webmaster:hostinfo and webmaster:verify (hostinfo alone only lists sites), then get a token via https://oauth.yandex.com/authorize?response_type=token&client_id=<id> and set GEOSEO_YANDEX_OAUTH_TOKEN. Docs.https://yourdomain.com/<key>.txt. Spec.Tools that need a key you haven't set return a clear error; everything else keeps working.
Example: only the keyless audit tools, for a lean agent context:
It binds to localhost by default. There is no built-in auth, so put it behind a proxy you trust before exposing it anywhere.
audit_page reads raw HTML by default. If a page looks like a JS shell (an empty SPA root or almost no text), it adds a js_rendering finding. Install the extra and pass render=True (or --render on the CLI) to audit the rendered DOM:
geoseo_status, list_llm_enginesgsc_list_sites, gsc_performance, gsc_inspect_url, gsc_submit_sitemapbing_list_sites, bing_query_stats, bing_page_stats, bing_url_info, bing_submit_url, bing_crawl_issuesyandex_list_sites, yandex_site_summary, yandex_query_stats, yandex_url_info, yandex_submit_url, yandex_crawl_issuesindexnow_submit_url, indexnow_submit_urlsperplexity_query, perplexity_citation_check, openai_query, claude_query, gemini_query, grok_query, brave_query, multi_llm_query, multi_llm_citation_checkaio_check, aio_citation_checkaudit_page, audit_site, find_broken_external_links, lint_schema_page, lint_schema_siteinternal_link_graph, suggest_internal_linksgenerate_llms_txt, validate_llms_txttrend_init, trend_stats, snapshot_gsc, snapshot_llm_citations, snapshot_serp_aio, trend_gsc, trend_llm_citationssuggest_internal_links uses TF-IDF by default (offline, free). Pass mode="openai", "gemini" or "local" (sentence-transformers) for embedding similarity; vectors are cached in SQLite by content hash.
For Yandex tools, pass a normal URL as site; it's matched to the Yandex host id (https:example.com:443), following the main mirror. yandex_url_info only covers pages in "Monitoring important pages" (Yandex has no arbitrary-URL inspect endpoint).
Snapshots are append-only and stored at $GEOSEO_DB. Schedule the snapshot_* tools weekly to build a private time series of your AI-search visibility.
Tracked in issues. Shipped in 0.4: broken-link prospector, schema linter, Grok and Brave citation engines, embedding-based link suggestions, Yandex Webmaster.
PRs welcome. Each engine is a module in src/geoseo_mcp/engines/ that exposes query() and returns the standard {engine, question, model, answer, citations, cited_domains, usage} shape; tools live in src/geoseo_mcp/tools/. See docs/architecture.md.
MIT. See LICENSE.
Source: README.md at commit 209e26f
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.
Takes no parameters.
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.
Takes no parameters.
Query GSC search analytics.
devicecountryend_datesite_urlrequiredrow_limitdimensionsstart_datesearch_typeGet 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.
urlrequiredsite_urlrequiredlanguage_codeSubmit (or resubmit) a sitemap URL to GSC. ``feedpath`` is the absolute URL of the sitemap, e.g. ``https://example.com/sitemap.xml``.
feedpathrequiredsite_urlrequiredList all Bing-verified sites for the API key owner.
Takes no parameters.
Last-6-months query stats from Bing Webmaster (clicks, impressions, position). ``site_url`` must match what Bing has verified, e.g. ``https://example.com/``.
site_urlrequiredPer-page stats from Bing Webmaster.
site_urlrequiredIndex status + crawl info for a single URL on Bing.
urlrequiredsite_urlrequiredSubmit a URL for fast crawling. Daily quota applies (default ~10/day).
urlrequiredsite_urlrequiredCrawl errors / blocked URLs / DNS issues reported by Bingbot.
site_urlrequiredList sites in the token owner's Yandex Webmaster account.
Takes no parameters.
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``).
siterequiredTop 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.
siterequiredlimitdevicedate_toorder_bydate_fromIndexing + search status for a URL in Yandex "Monitoring important pages".
urlrequiredsiterequiredQueue a URL for Yandex recrawl. Daily quota applies.
urlrequiredsiterequiredActive Yandex site diagnostics (by severity) plus sample broken internal links.
siterequiredNotify 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``).
urlrequiredBatch-notify search engines about up to 10,000 URLs (must share one host). Best for sitemap-wide rebuilds or large content updates.
urlsrequiredAsk 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.
modelquestionrequiredmax_tokenssystem_promptCitation share for ``target_domain`` across a Perplexity question batch.
modelquestionsrequiredtarget_domainrequiredAsk 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``).
modelquestionrequiredsystem_promptAsk Claude (with server-side web search) a question; return answer + cited URLs.
modelquestionrequiredmax_tokenssystem_promptAsk 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".
modelquestionrequiredsystem_promptAsk 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``).
modelquestionrequiredx_searchsystem_promptAsk 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``).
countrylanguagequestionrequiredAsk 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.
enginesquestionrequiredHow 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.
enginessamplesquestionsrequiredbrand_aliasestarget_domainrequiredmax_concurrencyReturn the LLM engines currently configured (have an API key).
Takes no parameters.
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.
glhlqueryrequiredlocationgoogle_domainFor 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.
queriesrequiredtarget_domainrequiredAudit 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")``
rendersourcerequiredRecursively 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.
limitfolderrequiredpatternFind 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.
folderrequiredpatterntimeoutmax_urlssite_hostcache_daysinclude_okconcurrencyValidate 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.
sourcerequiredRun ``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.
limitfolderrequiredpatternGenerate 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.
limitfolderrequiredpatternsite_urlrequiredsite_titlesite_summarysection_strategyValidate 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).
sourcerequiredAudit 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.
limitfolderrequiredpatternsite_hostSuggest 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.
modepagelimitmodeltop_kfolderrequiredpatternsite_hostCreate the local SQLite snapshot DB if it doesn't exist; return its path.
Takes no parameters.
Inventory of what's stored: row counts, sites/domains, oldest/newest snapshots.
Takes no parameters.
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"]``.
end_datesite_urlrequiredrow_limitdimensionsstart_datesearch_typeRun 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.
enginessamplesquestionsrequiredtarget_domainrequiredRun AIO citation check via SerpAPI and persist as ``serpapi_aio`` engine rows.
queriesrequiredtarget_domainrequiredTime-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.
pagelimitquerysite_urlrequiredPer-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}``.
limitenginetarget_domainrequired90% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
# Audit any page: title, meta, headings, schema, freshness, GEO quotability, 0-100 scoreuvx geoseo-mcp audit https://example.com
# Check a site's llms.txt against the specuvx geoseo-mcp llms-txt https://llmstxt.org
# Same audit after running JavaScript (for SPAs); needs the [render] extrauvx --from 'geoseo-mcp[render]' geoseo-mcp audit https://your-spa.com --render$ uvx geoseo-mcp audit https://example.comhttps://example.com score: 15/100 title: 'Example Domain' words: 27
8 issue(s): ✗ meta_description: Meta description should be 70-160 chars [length=0] ✗ h1: Exactly one H1 expected [found=0] ✗ word_count: Pages under 300 words rarely rank or get cited [words=27] ✗ schema: No JSON-LD schema found; LLMs and Google use this heavily ✗ canonical: Missing canonical URL ✗ open_graph: Missing core Open Graph tags (og:title, og:description) ✗ freshness: No published-date signal found; LLMs deprioritize stale content ✗ quotability: Few short, fact-dense sentences; LLMs prefer quotable lines [quotable_sentences=0]
3 check(s) passed. Use --json for the full report.npx @modelcontextprotocol/inspector uvx geoseo-mcpclaude mcp add geoseo -- uvx geoseo-mcp
# with keysclaude mcp add geoseo \ -e GEOSEO_OPENAI_API_KEY=sk-... \ -e GEOSEO_PERPLEXITY_API_KEY=pplx-... \ -- uvx geoseo-mcp{ "mcpServers": { "geoseo": { "command": "uvx", "args": ["geoseo-mcp"], "env": { "GEOSEO_OPENAI_API_KEY": "sk-...", "GEOSEO_ANTHROPIC_API_KEY": "sk-ant-...", "GEOSEO_GEMINI_API_KEY": "AIza...", "GEOSEO_XAI_API_KEY": "xai-...", "GEOSEO_BRAVE_API_KEY": "...", "GEOSEO_PERPLEXITY_API_KEY": "pplx-...", "GEOSEO_SERPAPI_API_KEY": "...", "GEOSEO_GOOGLE_CLIENT_SECRET": "/absolute/path/to/client_secret.json", "GEOSEO_BING_WEBMASTER_API_KEY": "...", "GEOSEO_YANDEX_OAUTH_TOKEN": "y0_...", "GEOSEO_INDEXNOW_KEY": "..." } } }}"env": { "GEOSEO_TOOLSETS": "audit,graph" }uvx geoseo-mcp serve --transport http --port 8000# MCP endpoint: http://127.0.0.1:8000/mcppip install 'geoseo-mcp[render]' && playwright install chromiumgit clone https://github.com/Rachit8484/geoseo-mcp.git && cd geoseo-mcpuv sync --extra devuv run ruff check src tests && uv run pytest