Skip to main content
Glama

GEOMCP is an open-source Model Context Protocol server for technical SEO and generative engine optimization (GEO). Connect it to an MCP-capable assistant to inspect HTML, structured data, crawler policies and sitemap documents without leaving your development workflow.

Every page finding includes a stable check ID, observed evidence and a concrete recommendation. Audit reports work as structured JSON, so your assistant can turn findings into code changes and compare the result.

  • Evidence you can inspect. Findings point to observed metadata, elements, counts and response details.

  • Works on your machine. No GEOMCP account, API key, telemetry or paid LLM dependency.

  • Useful before launch. Audit supplied HTML without making network requests.

  • Search and training stay distinct. Inspect declared crawler policies without treating training opt-outs as SEO failures.

  • Designed for a second pass. Compare checks after changes; unknowns remain coverage changes.

Get started

Requires Node.js 22+, npm and Git. This initial release is distributed through GitHub; an npm registry release is not required.

git clone https://github.com/WebDecoy/geomcp.git
cd geomcp
npm ci
npm run build
node dist/cli.js --help

Use the absolute path to dist/cli.js in your MCP client. The server communicates over stdio and waits for an MCP client when started without arguments.

Claude Desktop or Cursor

Add this entry to your client's MCP configuration (claude_desktop_config.json for Claude Desktop; .cursor/mcp.json for a Cursor project). Replace the example path with your actual clone location, then restart or enable the server.

{
  "mcpServers": {
    "geomcp": {
      "command": "node",
      "args": ["/absolute/path/to/geomcp/dist/cli.js"]
    }
  }
}

If your desktop app cannot find Node, use the absolute path returned by which node (macOS/Linux) or where node (Windows) as command.

VS Code

In .vscode/mcp.json:

{
  "servers": {
    "geomcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/geomcp/dist/cli.js"]
    }
  }
}

Start with a question

Audit https://your-site.com/guide for technical GEO issues. Show the evidence for the three most useful fixes, inspect its robots policy, and propose specific changes.

Audit this generated HTML before I deploy it. Keep unavailable HTTP checks separate from failures.

Compare these two GEOMCP reports. What improved, what regressed, and what could we not evaluate?

The included improve-page prompt guides the audit → fix plan → verification workflow. geomcp://methodology exposes scoring guidance directly to clients that support MCP resources.

Related MCP server: sightvane-mcp

Five tools, one workflow

Tool

Input

Result

audit_url

url

Fetch one public HTML page; return scored checks, evidence, coverage and up to eight prioritized fixes.

audit_html

html, url

Analyze supplied HTML offline. The URL resolves relative links; no request is made.

inspect_robots

url

Fetch the origin's /robots.txt; evaluate declared policies for the exact page path.

inspect_sitemap

url

Inspect one XML sitemap or sitemap index for syntax, locations, dates and duplicates.

compare_audits

before, after

Compare check statuses from two reports using the same rules version.

audit_url, inspect_robots and inspect_sitemap make public GET requests. The other tools run offline. All tools are read-only: they do not edit your files or deploy changes.

What it checks

26 page checks across seven categories. Rules are readable in src/audit.ts; the complete check IDs and weights are in docs/checks.md.

Category

Signals inspected

Discovery

Title, page description, canonical URL, index directives, Open Graph metadata

Structure

Document language, primary heading, heading order, main landmark, extractable HTML text

Semantics

JSON-LD syntax, entity types and contexts, publisher identity metadata

Media & interaction

Image alt attributes, table headers, form labels

Links

Internal links, descriptive labels, HTML navigation destinations

Evidence signals

Author attribution, machine-readable dates, supporting source links

Delivery

HTTP status, HTML Content-Type, HTTPS URL, responsive viewport

Robots inspection reports policies for Googlebot, Bingbot, OAI-SearchBot, ChatGPT-User, Claude-SearchBot, Claude-User, PerplexityBot, GPTBot and ClaudeBot. These are declared policies, not live requests made under those identities.

An actual report

examples/audit.json is generated from the included examples/page.html fixture. It is a reproducible example, not a customer result.

{
  "id": "canonical-url",
  "category": "discovery",
  "status": "warn",
  "weight": 2,
  "title": "Canonical URL",
  "evidence": "0 canonical elements; resolved URL: none",
  "recommendation": "Use one HTTP(S) canonical URL for the preferred version of this page."
}

You can also use the audit engine directly after building:

import { auditHTML } from './dist/index.js';

const report = auditHTML(html, 'https://example.com/guide');
console.log(report.priorities);

Understand the score

The score is a transparent technical checklist, with rules version 0.1.0:

pass = 1    warn = 0.5    fail = 0
score = round(100 × Σ(weight × value) / Σ(evaluated weights))
unknown checks are excluded

Core checks receive weights of 2 or 3; supporting checks receive 1. Reports include coverage and category scores so a high score with sparse evidence remains visible. Compare similar page types, coverage and the same rules version.

A checklist score does not predict AI citations, rankings, factual accuracy or signups. A public product page, private dashboard and editorial article have different needs. Intentional noindex, absent bylines and missing editorial dates can all be appropriate. No recommendation requires invented content, credentials, claims or reviews.

Network behavior & privacy

  • Runs locally. No telemetry, vendor API or account system. Reports are returned to the MCP client; your assistant provider's own data policies still apply.

  • Public fetches identify as GEOMCP/0.1 (+https://github.com/WebDecoy/geomcp). It does not impersonate AI vendors.

  • HTTP(S) only, ports 80/443, a 15-second total fetch deadline, four redirects maximum and a 2 MiB response limit. The same size limit applies to offline HTML input.

  • Private, loopback, link-local and reserved IP ranges are blocked. DNS answers are checked and pinned to each connection; redirects are revalidated. HTTPS downgrades are blocked.

  • No cookies, authentication headers, form submissions, JavaScript execution or browser automation. Requests ask for uncompressed content; unexpectedly compressed responses are rejected.

  • audit_url fetches one page and does not enforce robots.txt policy automatically. Use it on pages you are authorized to inspect; use inspect_robots when reviewing declared crawler preferences.

  • Page content is untrusted data. MCP tool descriptions and server instructions tell assistants to treat it as evidence, never as instructions.

The tool does not measure Core Web Vitals, computed visibility, rendered accessibility, actual crawler identity or index inclusion. Sitemaps and outbound links are inspected without following their destinations. Supporting links are evidence signals, not fact checking.

Development

npm ci
npm run build
npm test
npm run check
npm run artwork

Tests cover audit behavior, scoring, crawler rules, XML parsing, SSRF protections and a real MCP client/server stdio exchange. GitHub Actions runs the build and tests on Node.js 22 and 24. Artwork is generated from the editable SVG designs in scripts/artwork.mjs.

A live validation of all 193 WebDecoy sitemap pages exercised all five tools through a real SDK client and stdio server. It also checked a controlled missing-title/missing-H1 fixture, blocked a metadata IP, and verified the methodology resource and prompt. Reproduce the initial 12-page validation with npm run validate:site -- /tmp/geomcp-validation. The recorded scores describe checklist results, not search visibility.

See CONTRIBUTING.md for adding checks and SECURITY.md for private vulnerability reports.

Built by WebDecoy

WebDecoy builds bot detection for websites, applications, WordPress and Shopify. GEOMCP helps developers inspect discoverability; WebDecoy helps them understand the traffic that arrives.

If GEOMCP helps you ship a better page, give it a star or share a reproducible issue. Contributions and thoughtful new checks are welcome.

MIT licensed. Made for people who want to see the work behind the score.

Available Tools

5 tools
audit_htmlAudit supplied HTML offlineA
Read-onlyIdempotent

Audit HTML supplied by the user or a build pipeline. Makes no network requests. HTTP checks remain unknown. Base URL is used only to resolve links.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
htmlYes

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: no network requests are made and HTTP status checks will remain unknown, which tells the agent what the audit result cannot contain.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short, front-loaded sentences with no filler. The offline constraint and result limitation appear early, before the url clarification.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and only two required parameters, the description covers the critical semantics: input source, no network access, unknown HTTP results, and the role of the base URL. It is complete enough to call correctly, though it never routes the agent between this and audit_url.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry the parameter burden, and it does: it clarifies that 'url' is a base URL used only to resolve links (not a page to fetch) and that 'html' is the user-supplied markup to audit. This disambiguates the otherwise opaque uri-typed url parameter; only the length limits remain undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb (audit) and resource (user- or pipeline-supplied HTML), and 'Makes no network requests' implicitly separates it from the sibling audit_url, which must fetch over the network. It does not name the sibling explicitly, so differentiation is inferred rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'HTML supplied by the user or a build pipeline' implies the offline-input scenario, but the description never states when to choose this over audit_url (e.g., 'use when you already have HTML; use audit_url to fetch a live page'). Usage is implied rather than directed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

audit_urlAudit a public pageA
Read-onlyIdempotent

Fetch one public page as GEOMCP and audit server-delivered HTML. Returns evidence, scored checks, unknowns, and prioritized fixes. No JavaScript execution, vendor impersonation or citation prediction.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, open-world, non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: server-delivered HTML only, no JavaScript execution (so client-rendered content is invisible), and the explicit exclusions of vendor impersonation and citation prediction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, zero filler, and the core action (fetch + audit a public page) is front-loaded. Every clause carries information the agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read-only tool with no output schema, the description does the right work: it summarizes the return shape (evidence, scored checks, unknowns, prioritized fixes) and bounds the analysis. It could say more about failure modes for non-public or JS-rendered pages, but nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds the meaningful qualifier that the target must be 'one public page', but says nothing about URL format, length limits, or whether redirects/query strings are accepted. With only one parameter and 0% schema description coverage, the schema's uri format and maxLength carry the remaining semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: fetch one public page and audit server-delivered HTML. The 'fetch' framing implicitly distinguishes it from the sibling audit_html (which presumably audits supplied markup), but no sibling is named explicitly, so the differentiation is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: this is the tool for auditing a live public URL. There is no explicit when-to-use/when-not guidance, no mention of when to prefer audit_html or compare_audits, and the 'no JavaScript execution' line is a capability limit rather than routing advice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

compare_auditsCompare before and afterA
Read-onlyIdempotent

Compare two GEOMCP 0.1.0 check reports. Unknowns and absent checks are coverage changes, never improvements. Pass prior audit objects directly; extra fields are ignored.

ParametersJSON Schema
NameRequiredDescriptionDefault
afterYes
beforeYes

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description still adds real semantic value: 'Unknowns and absent checks are coverage changes, never improvements' encodes a non-obvious comparison rule the agent cannot derive from annotations or schema. It also notes that extra input fields are ignored, which clarifies input tolerance.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the operation and followed by the two rules that matter most. No filler, no restatement of the title or tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should describe what the comparison returns (e.g., per-check deltas, directionality) but does not. It partially compensates by stating how unknowns and absent checks are classified, yet an agent still cannot predict the response shape.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry the parameter burden. It correctly identifies that the two required parameters are full prior audit objects supplied 'directly' (not just checks arrays) and that extra fields are tolerated, which is useful. However, it does not explain the before/after ordering semantics or what happens on a version mismatch beyond what the schema's const already enforces.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource: 'Compare two GEOMCP 0.1.0 check reports.' The domain (GEO check reports) and the act (diffing) are unambiguous and clearly distinct from the audit/inspect siblings, though no sibling is named explicitly to reinforce the distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Pass prior audit objects directly; extra fields are ignored' tells the agent what to supply, which implies the tool is used on outputs of the audit_* tools, but there is no explicit when-to-use or when-not-to-use statement versus the sibling inspection tools. Usage is inferable rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

inspect_robotsInspect search and training policiesA
Read-onlyIdempotent

Fetch origin /robots.txt and report declared policies for search, AI retrieval and training separately at the supplied page path. Does not prove live vendor access.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the description's remaining job is interpretive context. It delivers that with 'Does not prove live vendor access', warning the agent that declared policy is not observed behavior, and clarifies the fetch is origin-level. It does not mention failure modes for missing or malformed robots.txt.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with no filler; the action and scope come first and the caveat second. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter, read-only inspection tool with no output schema, the description conveys both what is fetched and how to read the result (per-purpose policy classes, not proof of live access). Only the missing-robots.txt case and URL format expectations are absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

One parameter with 0% schema description coverage, so the description must carry the load. 'At the supplied page path' usefully implies the URL is reduced to its origin before fetching robots.txt, but it omits format requirements (absolute URI with scheme) and whether path/query are ignored. Partial compensation only.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (fetch origin /robots.txt, report declared policies) and scopes the result to search, AI retrieval, and training separately. It is clearly distinguishable from inspect_sitemap and the audit_* siblings, though it never names an alternative explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer you call this when you want a site's declared crawler/AI policies. There is no statement of when to prefer it over inspect_sitemap or audit_url, and no prerequisites (e.g. what happens if robots.txt is missing).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

inspect_sitemapInspect a sitemap documentA
Read-onlyIdempotent

Fetch one public XML sitemap or sitemap index. Report malformed locations, duplicate URLs, date syntax and samples. Does not fetch child maps or check indexing.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuine scope behavior beyond them: it processes exactly one document, refuses to recurse into child sitemaps, and performs no indexing check — all real limits an agent must know. It omits auth needs, size/timeout limits, and error behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, zero filler, with the core action front-loaded and the scope exclusions immediately after. Every clause carries information an agent would otherwise have to guess.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, no annotations gap, and a single-parameter signature, the description is nearly sufficient: it states what is fetched, what is reported, and what is deliberately not done. Only edge behavior (compressed sitemaps, fetch failures, very large documents) is left unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter with 0% schema description coverage; the schema supplies just type/keyword/format/maxLength with no wording. The description adds real meaning by constraining the value to a public XML sitemap or sitemap index URL, but says nothing about gzip-compressed maps or how errors on unreachable URLs are reported. Useful but partial compensation for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Fetch/Inspect/Report) and resource (one public XML sitemap or sitemap index), plus the exact anomaly classes it surfaces (malformed locations, duplicates, date syntax, samples). That resource scope alone separates it from audit_url, audit_html, and inspect_robots without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly bounds the tool: 'Does not fetch child maps or check indexing,' which preempts the common misuse of expecting recursive crawling or index-status verification. It stops short of naming the sibling to use instead (e.g., inspect_robots for robots.txt), so it is context-rich but not fully routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 5 tool updatesv0.1.0
    • First observedaudit_html
    • First observedaudit_url
    • First observedcompare_audits
    • First observedinspect_robots
    • First observedinspect_sitemap

TDQS

A4/5.0

Scored across 5 tools

Disambiguation5/5

Each tool targets a distinct input and action: audit_url (network page), audit_html (supplied markup), inspect_robots, inspect_sitemap, and compare_audits. The only near-pair, audit_url vs audit_html, is clearly separated by input source and network behavior in the descriptions.

Naming Consistency5/5

All names follow a consistent verb_noun snake_case pattern (audit_url, audit_html, inspect_robots, inspect_sitemap, compare_audits). Verbs vary (audit/inspect/compare) but each accurately reflects the operation without breaking the convention.

Tool Count4/5

Five tools is a tight, well-scoped set that maps cleanly onto the audit workflow. It is on the lean side, with no batch or multi-page variants, but nothing is redundant.

Completeness4/5

The set covers page auditing from both live and supplied HTML plus robots.txt, sitemap, and report comparison. Gaps exist for batch/multi-URL audits and other GEO-relevant artifacts like llms.txt, but the core lifecycle is workable.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    C
    maintenance
    Lets any AI agent audit any website for SEO, GEO/AEO, and speed problems, reporting issues and recommendations without modifying the site.
    4
    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.
    -
  • A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI agents to crawl live websites, audit AEO readiness, generate Schema.org @graph JSON-LD, llms.txt, ai.txt, and robots.txt, inject structured data into HTML, validate optimizations, and retrieve framework-specific code snippets.
    MIT