Skip to main content
Glama
GEO Analyzer MCP

GEO Analyzer MCP

by clance1

GEO Analyzer MCP

A self-hosted Model Context Protocol server for Generative Engine Optimization: measure how a company shows up in ChatGPT, Claude, Gemini (and optionally Perplexity), and get concrete fixes.

MCP prompt

Tool

What it does

/page-audit

page_audit

Tests a URL the way AI crawlers see it: robots.txt and real HTTP access for 16 AI user-agents, WAF/bot-challenge detection (Cloudflare, Vercel, Akamai), content parity, JS-only content, indexability, JSON-LD, sitemap, llms.txt. Score 0-100 + copy-paste fixes.

/ai-visibility

ai_visibility

Runs your preset queries and stable variants through each engine with web search on. Stores full answer text + native citations. Reports mention / citation / recommendation rate, rank vs competitors, share of voice, most-cited domains, citation-outreach opportunities, and lost queries.

/sentiment

sentiment

Asks engines directly about the company ("How is {company} at {service}?", reputation and head-to-head prompts). Scores recognition, sentiment −100..100, aspects (quality, price, timeline…), praise, concerns, and claims that contradict your ground-truth facts.

/full-analysis

full_analysis

All three, plus a GEO score (0-100), deltas vs the previous run, alerts, a prioritized action plan, campaign guidance and a Markdown/HTML report.

Those are MCP prompt names, not Claude Code slash commands. In Claude Code they appear in the / menu as /geo:page-audit (MCP) and run as /mcp__geo__page-audit; in Hermes they are listed by mcp__geo__list_prompts. Every prompt maps 1:1 onto the tool of the same name.

Supporting tools: get_job, get_run, list_runs, get_trends, compare_runs, list_projects, get_project, server_status.

Every run is persisted (SQLite index + report.md, report.html, data.json), so agents can talk about trends, not one-off answers.


Contents


Related MCP server: LLM Pulse MCP Server

Quick start

Requires Python 3.11+.

pip install "git+https://github.com/clance1/geo-analyzer-mcp"   # or: pip install -e . from a clone
geo-mcp init        # writes ~/.geo-mcp/projects.yaml and ~/.geo-mcp/.env
# add ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_API_KEY to ~/.geo-mcp/.env
geo-mcp doctor      # shows which engines are configured
geo-mcp run page-audit --project local-construction --format md

The package is not published on PyPI — install it from git (or a clone) as shown above.

Prefer not to install anything? uvx runs the same CLI straight from git — prefix any command with uvx --from git+https://github.com/clance1/geo-analyzer-mcp geo-mcp:

uvx --from git+https://github.com/clance1/geo-analyzer-mcp geo-mcp doctor

local-construction is a placeholder preset — init copies it verbatim. It points at https://www.localconstruction.example.com, a reserved example domain that does not resolve, so nothing is audited until you edit it. Replace the slug, company, website, queries and competitors with your own in ~/.geo-mcp/projects.yaml before you run anything for real.

Any subset of keys works; engines without a key are skipped with a warning. The page audit needs no keys at all.

Optional JS rendering for the page audit (detects content that only appears after JavaScript):

pip install "geo-analyzer-mcp[render] @ git+https://github.com/clance1/geo-analyzer-mcp" && playwright install chromium

Install as a Hermes Agent Plugin

hermes plugins install clance1/geo-analyzer-mcp
hermes plugins enable geo-analyzer-mcp

The plugin launches the server with uvx and registers the MCP server as geo, so the tools show up as mcp__geo__page_audit, mcp__geo__ai_visibility, … It also ships the geo-analyzer-mcp skill, which teaches the agent the list-projects → run → poll → report workflow and the dry_run cost guard.

uvx builds the installed plugin directory into a throwaway environment on first run and downloads the package's Python dependencies from PyPI, so the code that runs is exactly the commit Hermes installed — for a catalog install, the reviewed, pinned commit.

Portable packages install disabled — hermes plugins enable turns the plugin on (hermes plugins list shows the exact key). An interactive hermes plugins install offers to enable it right away; decline and run hermes plugins enable yourself. Requires uvx on PATH. The plugin ships no credentials: keys and presets come from ~/.geo-mcp/ (next section).

The plugin runs the server for you but does not install the geo-mcp command, so geo-mcp init is not on your PATH. Write ~/.geo-mcp/projects.yaml and ~/.geo-mcp/.env by hand, or run init once from a clone (uvx --from git+https://github.com/clance1/geo-analyzer-mcp geo-mcp init).

Configuration

geo-mcp init        # writes ~/.geo-mcp/projects.yaml and ~/.geo-mcp/.env
  • ~/.geo-mcp/.env — engine API keys: ANTHROPIC_API_KEY (Claude), OPENAI_API_KEY (ChatGPT), GOOGLE_API_KEY (Gemini), optionally PERPLEXITY_API_KEY. Any subset works; engines without a key are skipped with a warning. The page audit needs no keys at all.

  • ~/.geo-mcp/projects.yaml — one preset per company: website, aliases, queries, competitors, core services, ground-truth facts and alert thresholds. Copy the shipped example config/projects.yaml into this file and edit your copy — the shipped file says not to edit it in place. The Docker image is the exception: it mounts config/projects.yaml and sets GEO_MCP_PROJECTS to it, so edit that file for container runs.

geo-mcp doctor prints which engines are configured. Every other setting is an environment variable — see Configuration reference.

Project presets

projects.yaml holds one entry per company. Only company and website are required.

projects:
  local-construction:
    company: Local Construction Co.
    website: https://www.localconstruction.example.com
    aliases: ["Local Construction"]
    location: Springfield
    core_services: [General contracting, Kitchen remodeling, Bathroom remodeling]
    accolades: []                 # awards the company has won
    facts:                      # ground truth used to flag inaccurate AI claims
      - Service area is Springfield.
    competitors:
      - name: Example Builders Inc.
        website: https://www.example-builders.example.com
      - https://www.another-contractor.example.com  # shorthand works too
    generic_terms: ["construction company", "general contractor"]   # never count these as a brand mention
    queries:
      - Best general contractor Springfield
      - query: Kitchen remodeling contractor Springfield
        variants: ["home renovation companies near me"]   # optional: pin your own variants
    variants_per_query: 2       # generated once, cached, reused → like-for-like trends
    pages: []                    # extra URLs for page audits
    engines: [claude, chatgpt, gemini]
    alerts: { visibility_drop_pts: 10, sentiment_drop_pts: 15, min_ai_bots_allowed: 6 }

Presets are resolved in this order:

  1. GEO_MCP_PROJECTS — an override, not a fallback. If that path does not exist you get no presets, and the first tool call fails with Available: (none configured).

  2. config/projects.yaml relative to the current working directory, if that file exists.

  3. ~/.geo-mcp/projects.yaml — used only when step 2 finds nothing.

Step 2 is CWD-relative, so starting the server from a checkout of this repo silently prefers the repo's example preset over your edited ~/.geo-mcp/projects.yaml. Start the server from any other directory, or point GEO_MCP_PROJECTS at the file you want.

One exception to step 1: if GEO_MCP_PROJECTS is a relative path that does not exist, the server still falls back to ~/.geo-mcp/projects.yaml (and to $GEO_MCP_DATA_DIR/projects.yaml if you set that). Only an absolute GEO_MCP_PROJECTS is used exactly as given, with no fallback — which is why the Claude Desktop example above sets none.

Tools also accept ad-hoc company + website (+ queries, competitors) for one-off checks without a preset.

Variants are stable on purpose. They're generated once per query and cached in ~/.geo-mcp/variants/, so week-over-week changes reflect the engines, not new wording. Pass regenerate_variants=true to refresh.

Connect a client

Copy-paste snippets for every client are in examples/clients/.

Claude Code

# local (stdio)
claude mcp add geo -- geo-mcp serve
# remote (your self-hosted HTTP endpoint)
claude mcp add --transport http geo https://geo-mcp.example.com/mcp --header "Authorization: Bearer $GEO_MCP_TOKEN"

Prompts appear in the / menu as /geo:full-analysis (MCP); typing /mcp__geo__full-analysis local-construction also works (Claude Code docs).

Claude Desktop

claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "geo": {
      "command": "geo-mcp",
      "args": ["serve"]
    }
  }
}

No env block is needed: Claude Desktop launches the server from an arbitrary working directory, so the server finds ~/.geo-mcp/projects.yaml on its own. Keys are read from ~/.geo-mcp/.env. If geo-mcp isn't on PATH, use "command": "python", "args": ["-m", "geo_mcp", "serve"].

Cursor

.cursor/mcp.json — local (stdio):

{ "mcpServers": { "geo": { "command": "geo-mcp", "args": ["serve"] } } }

Or remote (your self-hosted HTTP endpoint):

{ "mcpServers": { "geo-remote": { "url": "https://geo-mcp.example.com/mcp",
  "headers": { "Authorization": "Bearer ${env:GEO_MCP_TOKEN}" } } } }

The shipped examples/clients/cursor-mcp.json has both, under different keys — geo for local, geo-remote for remote. Delete whichever one you don't use; a single mcp.json cannot hold two servers under the same key.

OpenAI Codex

~/.codex/config.toml (Codex MCP docs):

[mcp_servers.geo]
command = "geo-mcp"
args = ["serve"]
tool_timeout_sec = 120

# or remote:
# [mcp_servers.geo]
# url = "https://geo-mcp.example.com/mcp"
# bearer_token_env_var = "GEO_MCP_TOKEN"

Anything else

Any client that speaks MCP over stdio or Streamable HTTP works. HTTP endpoint: POST /mcp, auth Authorization: Bearer <GEO_MCP_TOKEN> or X-API-Key: <GEO_MCP_TOKEN>.

Long runs and client timeouts

Run tools wait up to wait_seconds (default 50s; 20s for full_analysis). If the run isn't done, they return status: "running" and a run_id; the agent polls get_job(run_id, wait_seconds=50). Progress notifications are sent while the client is waiting. This keeps every client under its tool timeout, regardless of how many queries you run.

Use dry_run: true on ai_visibility, sentiment and full_analysis to see every prompt and the exact number of engine calls first. page_audit has no dry_run parameter — it calls no engines and is free to run.

Inspect history from the CLI

geo-mcp history --project local-construction          # recent runs, newest first
geo-mcp trends  --project local-construction --kind full-analysis

Automation

No agent needed — the CLI runs the same code path and writes the same history:

# Mondays 07:00 — full analysis, alert on regressions
0 7 * * 1  cd /opt/geo-mcp && geo-mcp run full-analysis -p local-construction -q --out /srv/geo-reports --fail-on-alert
# Daily 06:30 — crawlability check
30 6 * * *  geo-mcp run page-audit -p local-construction -q

--fail-on-alert exits with code 3 when a run raised alerts, so cron mail / CI can flag it. Set GEO_WEBHOOK_URL to post a Slack-compatible summary on every completed run. More examples: examples/crontab, examples/systemd/, Windows Task Scheduler in examples/windows-task.ps1.

2. GitHub Actions

examples/github-actions/geo-weekly.yml runs the full analysis weekly, uploads the report as an artifact and fails the job on alerts. History lives in the runner's data dir, so for trends either point GEO_MCP_DATA_DIR at a cached path (shown) or call your self-hosted server's REST hook instead.

3. AI harnesses (agent writes the narrative)

# Claude Code, headless
claude -p "/mcp__geo__full-analysis local-construction" --allowedTools "mcp__geo__*" > weekly-brief.md
# Codex
codex exec "Use the geo MCP server: run full_analysis for local-construction, poll get_job until complete, \
  then write a one-page brief for the owner with the top 5 actions."

4. REST hooks (n8n, Zapier, Make, any scheduler)

When served over HTTP, the same runs are available as plain JSON endpoints (bearer auth):

curl -X POST https://geo-mcp.example.com/api/run/full-analysis \
  -H "Authorization: Bearer $GEO_MCP_TOKEN" -H "Content-Type: application/json" \
  -d '{"project": "local-construction"}'
# → 202 {"run_id": "...", "status": "running"}
curl -H "Authorization: Bearer $GEO_MCP_TOKEN" https://geo-mcp.example.com/api/runs/<run_id>

Endpoint

POST /api/run/{page-audit,ai-visibility,sentiment,full-analysis}

body: project, any tool params, optional wait_seconds

GET /api/runs?project=&kind=&limit=

run index with metrics

GET /api/runs/{run_id}

compact summary

GET /reports/{run_id}

HTML report (?format=md for Markdown; ?token= accepted for browser links)

GET /healthz

public health check

Self-hosting over HTTP

cp .env.example .env              # add API keys + GEO_MCP_TOKEN
docker compose up -d --build      # serves http://127.0.0.1:8765/mcp

The container reads config/projects.yaml from the repo (mounted read-only at /app/config), not ~/.geo-mcp/projects.yaml — edit the repo copy for container runs, or set GEO_MCP_PROJECTS to a mounted path of your own.

The compose file binds to localhost only. To reach it from cloud agents, put it behind your existing Cloudflare Tunnel — add an ingress rule:

ingress:
  - hostname: geo-mcp.example.com
    service: http://geo-mcp:8765     # if cloudflared shares the compose network; else http://localhost:8765

…and set GEO_MCP_ALLOWED_HOSTS=geo-mcp.example.com and GEO_PUBLIC_BASE_URL=https://geo-mcp.example.com so DNS-rebinding protection accepts the tunnel hostname and webhook messages link to reports. The server refuses to bind a non-localhost address without GEO_MCP_TOKEN (override with --insecure only behind another auth layer such as Cloudflare Access).

Forwarded headers. X-Forwarded-For / -Proto / -Host are only believed from the proxy's own address. Set GEO_MCP_TRUSTED_PROXIES to the address(es) or CIDR your tunnel uses (e.g. 127.0.0.1 when cloudflared runs on the same host, 172.16.0.0/12 for the compose network). With the variable unset the headers are ignored entirely, so no remote client can spoof its address or the scheme in the access log.

What the numbers mean

Metric

Definition

AI Visibility Index (0-100)

50% mention rate + 30% own-domain citation rate + 20% recommendation rate, over all usable answers

Mention rate

% of answers naming the brand (company, aliases, domain; generic_terms excluded)

Citation rate

% of answers citing your domain (any citation kind)

Recommend rate

% of answers framing you as a top recommendation or recommended option (judge model; falls back to rank 1)

Avg position

Order of first appearance among you + named competitors, when you appear

Share of voice

Your answer mentions ÷ mentions of you + named competitors

Citation opportunities

Third-party domains cited on answers where you were absent — listing / PR / outreach targets

Sentiment index (−100..100)

Mean sentiment of answers that recognize the company

Recognition rate

% of direct questions where the engine shows specific knowledge of the company

Page score (0-100)

Weighted: AI access 35%, content 25%, structured data 15%, indexability 15%, discovery 10%

GEO score (0-100)

40% visibility index + 30% page score + 30% sentiment, where sentiment = (index+100)/2 × recognition rate. Weights re-normalize if a section is skipped.

Citation kinds: inline = attached to a specific claim, source = retrieved during search, in_text = URL in the answer body.

Engine answers are stochastic and location/personalization-dependent. Treat single runs as samples; use get_trends / compare_runs and act on persistent patterns.

Page audit caveat: the crawler test spoofs user-agents from your server's IP. Firewalls that verify real bots by IP (Cloudflare Verified Bots, Vercel) may admit the genuine crawlers even when the spoofed request is challenged — confirm in your firewall logs before changing rules.

Configuration reference

All settings are environment variables (also read from ./.env and ~/.geo-mcp/.env). See .env.example.

Variable

Default

ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, PERPLEXITY_API_KEY

—

Any subset

GEO_DEFAULT_ENGINES

claude,chatgpt,gemini

Used when the project doesn't list engines

GEO_CLAUDE_MODEL / GEO_CHATGPT_MODEL / GEO_GEMINI_MODEL / GEO_PERPLEXITY_MODEL

claude-sonnet-5-5 / gpt-6.1-sol / gemini-3.8-flash / sonar

Pin to the models your audience actually uses

GEO_CLAUDE_WEB_SEARCH_TOOL

web_search_20260318

Falls back to older tool versions automatically

GEO_JUDGE_PROVIDER

auto

anthropic | openai | gemini | none (lexical fallback)

GEO_ANALYST_MODEL

claude-sonnet-5-5

Writes the full-analysis brief

GEO_MAX_QUERIES_PER_RUN

60

Hard cap on prompts per engine per run (cost guard)

GEO_ENGINE_CONCURRENCY / GEO_ENGINE_TIMEOUT_S / GEO_MAX_RETRIES

4 / 120 / 4

GEO_MCP_DATA_DIR

~/.geo-mcp

Run history, reports, variant cache

GEO_MCP_PROJECTS

config/projects.yaml

Absolute path to the presets file; overrides the lookup entirely

GEO_MCP_HOST / GEO_MCP_PORT

127.0.0.1 / 8765

HTTP transport

GEO_MCP_TOKEN

—

Bearer token for HTTP (required for non-localhost binds)

GEO_MCP_ALLOWED_HOSTS

—

Public hostnames (tunnel/reverse proxy), comma-separated

GEO_PUBLIC_BASE_URL

—

Used for report links in webhooks

GEO_WEBHOOK_URL

—

Slack-compatible POST on run completion (includes alerts)

GEO_ALLOW_PRIVATE_TARGETS

false

Allow page audits of private/LAN addresses

GEO_MCP_TRUSTED_PROXIES

—

Peers whose X-Forwarded-* headers may be believed (IP or CIDR, comma-separated). Unset = the headers are ignored

Security

  • HTTP auth: constant-time bearer-token check on every route except /healthz. Generate a token with python -c "import secrets; print(secrets.token_urlsafe(32))". A report link may carry the token as ?token=… so it opens in a plain browser; the token is dropped from the request as soon as it has been read, so it is never written to the access log.

  • SSRF guard: page audits refuse private, loopback, link-local, CGNAT (RFC 6598) and cloud-metadata addresses on every request and every redirect hop. The hostname is resolved again at connect time and the socket is opened to that validated address only — so a name that answers with a public IP during the check and a private IP at connect time (DNS rebinding) still cannot reach an internal host. Only the socket target changes: the URL, the Host header, TLS SNI and certificate verification stay on the hostname.

  • Report rendering: the HTML report is built from untrusted text (audited URLs, engine answers, model briefs, finding snippets). Those values are tag-stripped and escaped where they are interpolated, the generated HTML is then sanitised with nh3 against an allowlist of the report's own tags, and the page is served with Content-Security-Policy: default-src 'none' — no script can run in a report, and the JSON-LD fix snippet stays copy-pasteable as text.

  • DNS-rebinding protection is on for localhost binds and for any host listed in GEO_MCP_ALLOWED_HOSTS.

  • Secrets are only read from the environment / .env; server_status reports which keys are set, never their values. Keep .env out of git (it's in .gitignore).

  • Cost control: dry_run, GEO_MAX_QUERIES_PER_RUN, per-engine concurrency limits, and usage counters in each run's data.

Development

pip install -e ".[dev]"
pytest -q          # fake engines + local HTTP fixtures; no network or keys needed
ruff check src tests

Add an engine by subclassing geo_mcp.engines.Engine (implement _ask) and registering it in engines/__init__.py; tests can inject engines with register_engine().

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Unifies traditional SEO and Generative Engine Optimization (GEO) for Google, Bing, Yandex, and major LLMs, providing tools for search performance analysis, citation tracking, on-page audits, and internal link graph analysis.
      47
      36 PyPI
      3
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Monitors brand mentions, citations, sentiment, competitor share of voice, and GEO performance across AI search engines.
      1
      MIT
    • -
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to perform comprehensive SEO and GEO measurements, including site audits, keyword research, ranking tracking, and brand visibility analysis across search engines and generative AI platforms.
      -