Skip to main content
Glama

SEO MCP Server

Chat with your site's SEO — with real data, not guesses.

Crawl a site, audit its on-page factors, read your actual Google Search Console performance, measure Core Web Vitals and compare against a competitor — from inside Claude, Cursor or any MCP client.

npm npm downloads CI Node MCP License: MIT

Designed, built & maintained by SoyRage Agency

⚡ No site, no credentials, no setup → try it in 30 seconds.


📑 Table of contents


Related MCP server: Wingate SEO MCP

⚡ Try it in 30 seconds

Demo mode serves a small fabricated site and a fabricated Search Console history, so you can see exactly what every tool returns before pointing it at anything real. No credentials, no network access.

{
  "mcpServers": {
    "seo": {
      "command": "npx",
      "args": ["-y", "@soyrageagency/seo-mcp"],
      "env": { "SEO_MCP_DEMO": "true" }
    }
  }
}

Restart your client and ask: “Audit my site.”

The fake site is deliberately imperfect — a 404 linked from an article, a page missing its H1, a title 83 characters long, images with no alt text, a page that quietly says noindex. A demo where everything is fine would teach you nothing about what the tool actually finds.


📦 Install

Nothing to clone or build. Add this to your MCP client's config (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "seo": {
      "command": "npx",
      "args": ["-y", "@soyrageagency/seo-mcp"],
      "env": {
        "SEO_MCP_SITE": "https://yoursite.com",

        // Optional, but this is where the real data is — see below
        "GSC_SERVICE_ACCOUNT_FILE": "/absolute/path/to/service-account.json",
        "GSC_SITE_URL": "https://yoursite.com/",

        // Optional: a free key, avoids PageSpeed rate limits
        "PAGESPEED_API_KEY": "AIza…"
      }
    }
  }
}

npx fetches the package on first run and keeps it current. A ready-to-edit copy lives in examples/claude_desktop_config.json.

Everything works with no credentials at all — you get the crawler and the on-page auditor, just not the real search data.


🧭 What it does

Most SEO tooling hands you a dashboard and leaves you to interpret it. This hands an LLM the underlying data, so you can ask a question in your own words and get an answer about your site.

Every screenshot below is the real, unedited output of the tool named in its title bar, generated by npm run shots against the demo site. If the tool's output changes, the screenshots are regenerated, not retouched.

Crawl a whole site

crawl_site finds what only a crawl can see: broken URLs and the page that links to them, duplicate titles, missing basics as a proportion, and pages buried too deep to be crawled often. link_graph, find_orphan_pages and find_duplicate_content go further into the same crawl.

Audit one page

audit_page reports every on-page signal for a single URL, with findings ranked by impact instead of listed flat.

Read real Search Console data

search_console_queries returns what Google actually recorded — not an estimate from a third-party index.

Compare two periods

search_console_compare answers the question people actually ask: is this going up or down, and because of what?

Measure Core Web Vitals

pagespeed keeps field data — what real Chrome users experienced, the part tied to ranking — separate from the lab simulation. Conflating the two is the standard mistake.

Compare against a competitor

compare_competitor puts the two pages side by side and then says what they do that you do not.

Draft a title and description

generate_meta gathers the evidence — current tags, structure, and the queries that already bring you impressions — and hands it over with the limits stated. It does not fill in a template, because a templated Buy X | Brand is worse than what the model writes from the page's real content.


🧩 Chrome extension — zero setup

The MCP server is for asking questions. The extension is for landing on a page and immediately knowing what you are looking at — no client, no credentials, no config. Install it, click the button, done.

It scores three things separately, because they fail independently: a page can rank beautifully and convert nothing.

SEO

A search-result preview showing what Google will actually display, measured in pixels rather than characters — Google truncates by rendered width, so a title of capitals is cut far sooner than one of narrow letters. Plus findings ranked by severity, the full heading outline, images without alt, anchor-text problems, structured data, lang and hreflang.

Leads

The contact details, extracted. Emails, phone numbers, WhatsApp, postal address, tax id and social profiles — from mailto:/tel: links, JSON-LD and a deliberately strict text scan. On a prospect's site, this is the lead.

Then the conversion audit: are there calls to action, and are any visible without scrolling? Is there a contact form? Any trust signals — testimonials, reviews, guarantees, case studies? Is a live chat available? And is anything being measured at all?

Stack

What a competitor is running tells you more about their strategy than their copy does. CMS, framework, and every analytics and ad pixel on the page. A Meta pixel means they are buying traffic. A session-recording tool means somebody is watching behaviour. No pixels at all means nobody is measuring anything — which is a finding in itself.

Two things the crawler cannot see

The extension is not a smaller copy of the server. It runs in a real browser:

  • The rendered page. If a site builds its content with JavaScript, an HTTP fetch gets an empty shell. The extension reads the DOM you are looking at. Comparing the two is often the finding.

  • Real Core Web Vitals for that load — the Largest Contentful Paint, TTFB and bytes transferred your browser measured, not a simulation. Plus images served at more than twice their displayed size, which costs bandwidth on every single visit and is invisible unless you look for it.

Copy puts the whole report on your clipboard as text — contact details, stack, measurements and every finding — ready for a doc, a ticket, or straight into Claude.

Install

Not on the Chrome Web Store yet, so load it unpacked — about thirty seconds:

  1. Download or clone this repo.

  2. Open chrome://extensions.

  3. Turn on Developer mode, top right.

  4. Load unpacked → select the extension folder.

  5. Pin it, then click it on any page.

What it can and cannot do

Worth being precise, because this is where comparable tools overpromise:

✅ Audit any page — yours, a client's, a competitor's

It reads what your browser already loaded.

✅ See JavaScript-rendered content

It reads the live DOM.

✅ Pull contact details for prospecting

From links, schema and a strict text scan. Only what the page publishes.

❌ Show heatmaps of your visitors

An extension only runs for whoever installed it. Your visitors will not install yours. Visitor analytics needs a snippet on the site — that is why Hotjar and Clarity work the way they do, and it is on the roadmap.

Privacy

It requests activeTab, not host permissions: it can read a page only after you click the button, and only that tab. No content script runs on pages you have not asked about, nothing is sent anywhere, and there is no account or analytics. The report exists in the popup until you close it.


🧪 Worked examples

Real questions, and what the assistant does with them.

Calls crawl_site. Comes back with the 404 and the article that links to it — which is the part that turns a finding into a fix, because you now know where to edit. Also surfaces the page quietly serving noindex, which is the single most expensive thing to have wrong and the least visible.

Calls search_console_queries with dimension: "page". High impressions with a low CTR means Google shows you and people choose someone else — usually a snippet problem rather than a ranking problem, and one of the cheapest things to fix. Follow it with generate_meta on the worst offender.

The why-did-traffic-drop prompt. It compares the window against the one before it, then breaks the loss down by page, query, device and country, because a drop concentrated in one page and a drop spread evenly have completely different causes.

The prompt explicitly tells the assistant not to reach for "a Google update" unless the pattern actually fits one — broad, sudden, sitewide. It is the explanation that requires no evidence, which is exactly why it gets used when there is none.

The beat-competitor prompt: compare_competitor for the on-page differences, audit_page on each for the detail, search_console_queries filtered to your URL for what you are already close on.

It is also told to say when the gap looks off-page. Sending you off to rewrite headings when the real difference is 400 referring domains wastes your week, and this server cannot see links pointing at you.

list_sitemap for what the site says it publishes, crawl_site for what it actually links to. The gap between the two is where stale URLs, orphan pages and forgotten sections live.

The audit-site prompt against a site you do not own. It obeys robots.txt, identifies itself honestly and paces itself, so you get the picture without being rude to their server. Everything is read-only.


🔑 Connect Google Search Console

This is the step worth doing. Without it, everything about search intent is inference; with it, the assistant is working from what Google actually recorded.

A service account is the easier path — no browser flow, no token to refresh.

  1. In Google Cloud Console, create a project and enable the Google Search Console API.

  2. Create a service account and download its JSON key.

  3. Open the JSON and copy the client_email — it looks like something@project.iam.gserviceaccount.com.

  4. In Search Console → your property → Settings → Users and permissions → Add user, paste that email and give it Full or Restricted access.

  5. Point the server at the key:

"env": {
  "GSC_SERVICE_ACCOUNT_FILE": "/absolute/path/to/key.json",
  "GSC_SITE_URL": "https://yoursite.com/"
}

Then ask: “What did we rank for last month, and what moved?”

"env": {
  "GSC_CLIENT_ID": "…apps.googleusercontent.com",
  "GSC_CLIENT_SECRET": "…",
  "GSC_REFRESH_TOKEN": "…",
  "GSC_SITE_URL": "https://yoursite.com/"
}

If Search Console is not configured, its tools do not register at all — and the server says why in its startup log. A tool that can only fail is worse than one that is not there.


🧰 Tool reference

Tool

What it does

crawl_site

Crawl and report site-wide problems: broken URLs with their referrers, duplicate titles and descriptions, missing basics, crawl depth, then the worst individual findings.

list_sitemap

The URLs a site declares, following the sitemap index. Often revealing on its own — what a site publishes is frequently not what it links to.

audit_page

Every on-page signal for one URL, ranked by impact. showOutline adds the full heading structure.

compare_competitor

Your page and a competitor's, field by field, ending in what they do that you do not.

search_console_queries

Real performance by query, page, country, device or date. Filterable to a single URL.

search_console_compare

A window against the one before it: what gained, what lost ground, what dropped out entirely.

list_search_console_sites

Which properties your credentials can read, and at what permission level.

pagespeed

Core Web Vitals, field data separated from the lab simulation.

generate_meta

Assembles the evidence for a new title and description — current tags, structure, and the queries that already work.

link_graph

PageRank over the internal links: where authority accumulates, which important pages are starved of it, which minor pages hoard it.

find_orphan_pages

Indexable pages nothing links to — reachable only from the sitemap, crawled rarely, invisible page by page.

find_duplicate_content

Pages saying the same thing in different words, by exact phrase overlap with site boilerplate excluded.

validate_structured_data

Schema checked against what Google requires for the rich result each type is for, not merely listed.

check_hreflang

Reciprocity, self-reference and valid codes across the crawl — where hreflang actually breaks.

find_broken_links

Outbound links that no longer resolve, with the pages that link to them.

serp_preview

The result as Google will render it, measured in pixels.Try a different title without editing the page.

about

Version, configuration and which capabilities loaded. Start here when a tool is missing.


💬 Guided workflows (prompts & resources)

Tools answer a question you already knew how to ask. SEO is a field where most people do not know which question to ask — so this server also ships MCP prompts, which your client lists for you.

Prompt

What it does

audit-site

Full sweep, ending in the three things to fix first with what each is plausibly worth. Narrow it with technical, content or performance.

why-did-traffic-drop

Works out what actually changed from real Search Console data.

improve-page

One URL end to end: what it has, what it already ranks for, how fast it is, then a specific edit list.

beat-competitor

Why their page outranks yours — and honest about what is not visible from here.

Each prompt names the tools to call, the order, and what a good answer looks like: verdict first, findings ranked, no padding, and ground every claim in tool output. An SEO audit full of confidently invented numbers is worse than no audit, so the instruction is explicit rather than hoped for.

Two resources are exposed as attachable context:

  • seo://server/capabilities — what is loaded and how it is configured.

  • seo://reference/checklist — every check and the threshold behind it, so the numbers in an audit can be questioned rather than taken on faith.


🌐 Run it over the network (HTTP)

By default an MCP server talks over stdio: your client starts it as a child process on your machine. Set one variable and it serves Streamable HTTP instead, so one instance can serve a whole team:

SEO_MCP_HTTP=true \
SEO_MCP_HTTP_TOKEN="$(openssl rand -hex 32)" \
SEO_MCP_SITE=https://yoursite.com \
npx -y @soyrageagency/seo-mcp
{
  "mcpServers": {
    "seo": {
      "type": "http",
      "url": "http://10.0.0.5:8621/mcp",
      "headers": { "Authorization": "Bearer <the token you generated>" }
    }
  }
}

It binds loopback by default and warns loudly if you start it without a token. Anyone who can reach the port can crawl anything the server can reach and read your Search Console data, so keep it behind your VPN. GET /health needs no token, for container healthchecks.


🐳 Run it in Docker

docker run --rm -i \
  -e SEO_MCP_SITE=https://yoursite.com \
  -v /path/to/key.json:/keys/gsc.json:ro \
  -e GSC_SERVICE_ACCOUNT_FILE=/keys/gsc.json \
  ghcr.io/soyrageagency/seo-mcp

Keep -i and do not allocate a TTY: stdout is the JSON-RPC stream. To serve it over the network instead, add -p 8621:8621 -e SEO_MCP_HTTP=true -e SEO_MCP_HTTP_HOST=0.0.0.0 -e SEO_MCP_HTTP_TOKEN=….


⚙️ Configuration reference

Everything is settable by environment variable, by seo-mcp.config.json, or by a local .env — in that order of precedence.

Variable

Default

What it does

SEO_MCP_SITE

—

Default site, so tools do not need the URL every time.

SEO_MCP_DEMO

false

Fabricated site and search data. No network access at all.

SEO_MCP_MAX_PAGES

200

Hard cap on pages per crawl.

SEO_MCP_MAX_DEPTH

3

How many links deep to follow.

SEO_MCP_CONCURRENCY

4

Parallel requests.

SEO_MCP_DELAY_MS

200

Pause between requests to the same host.

SEO_MCP_TIMEOUT_MS

15000

Per-request timeout.

SEO_MCP_RESPECT_ROBOTS

true

Obey robots.txt. Only turn this off for a site you control.

SEO_MCP_USER_AGENT

SeoMcpServer/1.0 (+…)

How the crawler identifies itself.

GSC_SITE_URL

SEO_MCP_SITE

Search Console property. Mind the trailing slash, or use sc-domain:.

GSC_SERVICE_ACCOUNT_FILE

—

Path to a service-account JSON key.

GSC_SERVICE_ACCOUNT_JSON

—

The key inline, for clients that only pass env vars.

GSC_CLIENT_ID / GSC_CLIENT_SECRET / GSC_REFRESH_TOKEN

—

The OAuth alternative.

PAGESPEED_API_KEY

—

Free key. Without it PageSpeed is rate-limited.

SEO_MCP_HTTP

false

Serve over HTTP instead of stdio.

SEO_MCP_HTTP_HOST / PORT / PATH / TOKEN

127.0.0.1 / 8621 / /mcp / —

HTTP transport settings.

SEO_MCP_PLUGINS

(all)

Allowlist: crawl,audit,searchconsole,pagespeed,meta,prompts.

SEO_MCP_DISABLED_PLUGINS

—

Blocklist. Always wins over the allowlist.

SEO_MCP_LOG_LEVEL

info

debug, info, warn, error.


🛡️ How it behaves on other people's servers

Every crawl hits somebody's server, often one you do not own — a competitor, a client's staging box. So the crawler is deliberately conservative:

  • It identifies itself honestly. The default User-Agent names the tool and links to this repo, so a site owner can see who hit them and block it.

  • It obeys robots.txt, including wildcards, $ anchors, longest-match precedence and per-agent groups. There is an override, and it warns you every time you use it.

  • It honours Crawl-delay, and paces itself per host regardless.

  • It is bounded by page count and depth, and gives up rather than hanging.

  • It follows redirects by hand, up to five hops, because the chain itself is a finding worth reporting.


🚫 What it will not do

Saying this plainly is more useful than another feature list:

  • It will not change your site. No edits, no submissions, no settings.

  • It will not invent numbers. The server's instructions tell the assistant to ground every claim in tool output and to say when it is inferring.

  • It will not tell you a page is "optimised". It reports conventions and thresholds. Relevance and links matter more than any of them, and a page can pass every check here and rank nowhere.

  • It has no backlink data. Nothing here sees links pointing to you.

  • No telemetry. Nothing leaves your machine except the requests you asked for: the sites you crawl, and Google's APIs when you configure them.


🩺 Troubleshooting

It does not register without credentials. Run about — it reports whether Search Console is connected and lists which capabilities loaded. The server also logs the reason on startup.

Run list_search_console_sites to see exactly which properties your credentials can read. The usual cause is a mismatch in how the property is verified: https://example.com/ (with the trailing slash), https://www.example.com/ and sc-domain:example.com are three different properties to Google.

For a service account, also check you added its client_email as a user on the property itself — enabling the API is not enough.

Set PAGESPEED_API_KEY. The key is free and takes a minute to create; without one the quota is tiny.

Two common causes. Either robots.txt is blocking the crawler — the report lists those URLs under NOT CRAWLED with the reason — or the site renders its content with JavaScript, and a plain HTTP fetch sees an empty shell. Rendered crawling is on the roadmap.

SEO_MCP_DEMO is still true. Remove it, or set it to false.


🧪 Development

git clone https://github.com/soyrageagency/seo-mcp-server.git
cd seo-mcp-server
npm install
npm run build

npm test        # 25 unit tests: robots.txt parsing, extraction, audit rules
npm run smoke   # 42 checks end to end: boots the real server and drives it
npm run inspect # the MCP Inspector, against your local build

npm run shots   # regenerate the README screenshots from real output
npm run gif     # regenerate the demo GIF
npm run banner  # regenerate the sponsor banner and social card
npm run icons   # regenerate the extension icons

npm run extension:shots  # load the extension in a real Chrome and screenshot it
npm run extension:gif    # the extension demo GIF

npm run dev watches and rebuilds. TypeScript strict, with noUnusedLocals, noUnusedParameters, noImplicitReturns and noFallthroughCasesInSwitch. CI runs the whole suite on Linux and Windows.


🗺️ Roadmap

The full roadmap — shipped, next, and what is deliberately not planned — lives in ROADMAP.md.

The short version: self-hosted visitor analytics with click and scroll heatmaps (a cookieless snippet, since an extension can only ever see its own installer), JavaScript-rendered crawling, and audits that remember so the question becomes "what changed since last week". Backlink data and keyword-volume estimates are not planned, because doing either honestly needs an index this project will never have.


💙 Support the project


🖋️ Credits & License

Designed, built and maintained by SoyRage Agency — https://soyrage.es/

Part of a family of self-hosting tools you can talk to: Proxmox MCP · Docker MCP · RageVault

Released under the MIT License — use it, modify it, self-host it, ship it commercially.

If you build something on top of it, a link back to soyrage.es is appreciated but never required.

© 2026 SoyRage Agency — https://soyrage.es/ · Made with care in Valencia, Spain.

Available Tools

14 tools
aboutAbout this serverA

Version, credits and the current configuration — which capabilities are loaded, whether Search Console is connected, and whether demo mode is on. Useful when a tool is missing and you want to know why.

Inputs: no named parameters.

audit_pageAudit one pageA

Fetch one URL and report every on-page SEO signal — title, description, headings, canonical, indexability, structured data, images, links, language and page weight — with findings ranked by impact rather than listed flat. Read-only.

Inputs: url (required), showOutline.

check_hreflangCheck hreflangA

Crawl the site and validate its hreflang across pages: reciprocity, self-reference, valid language and region codes, duplicate or multiple x-default. Faults here are invisible page by page — every page looks correct and the cluster is still ignored, because a declaration Google cannot verify from both ends is dropped entirely.

Inputs: site, maxPages.

compare_competitorCompare against a competitorA

Audit your page and a competitor's side by side, and report only where they differ. Use it to answer 'what are they doing that we are not' for a query you both target. Read-only, and it fetches both pages.

Inputs: url (required), competitor (required).

crawl_siteCrawl a siteA

Crawl a site and report the problems only visible across pages: broken URLs and what links to them, duplicate titles and descriptions, missing basics counted as a proportion, and pages buried too deep to be crawled often. Seeds from the sitemap when there is one. Read-only, obeys robots.txt and paces itself.

Inputs: site, maxDepth, maxPages, listPages, +1 more.

find_duplicate_contentFind near-duplicate pagesA

Find pages that say substantially the same thing in different words — a template filled in forty times, product variants with one word changed. Identical titles are easy to spot; this catches the expensive kind, where two pages compete for one query and neither wins.

Inputs: site, maxPages, threshold.

find_orphan_pagesFind orphan pagesA

Find indexable pages that nothing on the site links to. They are usually reachable only from the sitemap, which means they get crawled rarely and rank poorly regardless of how good they are. One of the highest-value findings a crawl produces, and invisible page by page.

Inputs: site, maxPages.

generate_metaDraft a title and meta descriptionA

Collect everything needed to write a strong title tag and meta description for a page: what it currently has, its headings, its opening prose, and — when Search Console is configured — the queries people already use to find it. Returns the evidence and the length limits; you write the copy from the page's actual content.

Inputs: url (required), keyword, variants.

list_sitemapRead the sitemapA

List the URLs a site declares in its sitemap, following the sitemap index when there is one. Useful on its own to see what the site thinks it publishes, which is often not what it actually links to.

Inputs: site, limit.

pagespeedCore Web VitalsA

Run PageSpeed Insights on a URL and report Core Web Vitals. Separates lab data (a Lighthouse simulation) from field data (what real Chrome users experienced), because only the second is what Google ranks on. Slow: Lighthouse runs server-side and takes up to a minute.

Inputs: url (required), strategy.

serp_previewPreview the search resultA

Render a page's title and description the way a Google result will show them, measured in pixels rather than characters. Google truncates by rendered width, so a title of capitals is cut far sooner than one of narrow letters — the character count everyone quotes misleads on exactly the titles worth checking.

Inputs: url (required), title, description.

validate_structured_dataValidate structured dataA

Check a page's JSON-LD against what Google actually requires for the rich result each type is for. Having schema and being eligible for a rich result are different things: a Product with no offer, a Recipe with no ingredients or a rating above its own scale are all valid JSON that earns nothing.

Inputs: url (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 14 tools

    Disambiguation5/5

    Each tool targets a clearly distinct concern—site-wide crawl issues, individual page audits, external link checking, internal link analysis, orphans, duplicates, structured data, and hreflang. Even related tools like crawl_site and find_duplicate_content are differentiated by whether they catch exact duplicates or semantic similarity.

    Naming Consistency4/5

    Most tools follow a clear verb_noun snake_case pattern such as crawl_site, find_broken_links, and validate_structured_data. A few exceptions like about, pagespeed, serp_preview, and link_graph break the pattern, but the naming remains readable and predictable overall.

    Tool Count5/5

    14 tools is well within the ideal range for a specialized SEO server. Each tool addresses a discrete diagnostic need, and the count feels comprehensive without being bloated or redundant.

    Completeness5/5

    The toolset covers the major technical SEO workflows: crawling, page audits, performance, metadata, internal links, orphans, duplicates, structured data, hreflang, sitemaps, and competitor comparison. There are no obvious dead ends or missing life-cycle operations for an analysis-focused SEO server.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Integrates SEO analysis and Google Search Console data directly into Claude Code and Cursor. Performs real-time site audits, detects technical SEO issues, validates meta tags, generates structured data, and provides AI-powered recommendations for both production sites and local development servers.
      19
      3
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables natural-language, read-only analysis of your own Google Search Console and Google Analytics 4 data, including search performance, engagement, sitemap health, ranking opportunities, and deterministic SEO audits through MCP clients like ChatGPT.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Checks what GPTBot, ClaudeBot, PerplexityBot and 50+ other AI crawlers can read on a site and what its access policy allows, checks whether a page permits search, answers, training or agent use (with a signed receipt), generates llms.txt, robots.txt and JSON-LD, and reads your Answer Analysis. Nine tools for Claude Desktop, Cursor and other MCP clients.
      9
      139 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables Claude, ChatGPT, Cursor, and other MCP clients to query Google Search Console, GA4, PageSpeed Insights, and live SERPs through 38 read-only SEO tools for quick wins, content decay, indexing, Core Web Vitals, AI traffic, and conversion analysis.
      2
      MIT