AgenticSEO MCP Server

AgenticSEO is a local TypeScript MCP server that gives coding agents structured SEO evidence. It audits public or localhost pages, identifies the affected page and an evidence-backed CSS selector when the source provides one, and saves a complete, redacted report for every call.

The server never intentionally edits an audited website or repository. Its only writes are numeric run directories under its own report root.

Requirements

• Node.js 22.19 or newer. The project plan originally named 22.18, but the pinned Lighthouse 13.4.0 package requires Node 22.19+.

• Google Chrome or Chromium for Lighthouse, Unlighthouse, and rendered-URL structured-data validation.

• Google credentials only when using Search Console tools.

• A CrUX API key only when using query_crux.

Related MCP server: mcp-seo

Install and verify

Use the published package

After the first public release, configure a stdio-capable MCP client to launch AgenticSEO directly from npm:

{
  "mcpServers": {
    "agenticseo": {
      "command": "npx",
      "args": ["-y", "agenticseo-mcp@0.1.2"]
    }
  }
}

Pinning the version makes reviewer runs reproducible. AgenticSEO and Chrome run on the reviewer's computer, so the server can audit that computer's localhost projects. No Google credentials are required for Lighthouse, Unlighthouse, or local structured-data validation.

Develop from source

git clone https://github.com/mahmoud-the-dev/agenticseo-mcp.git
cd agenticseo-mcp
npm ci
npm run check
npm run smoke:stdio

npm run check runs strict TypeScript validation, unit/contract tests, and the production build. npm run smoke:stdio then runs explicit legacy and MCP 2026-07-28 lanes against the same compiled dist/cli.js artifact. The server automatically negotiates the applicable era: current legacy hosts continue through their initialize path, while clients that opt into MCP 2026-07-28 use discovery without an initialize sequence. Both expose the same tools, resources, and schemas. Protocol and startup diagnostics are JSON lines on stderr only; stdout remains reserved for the MCP stdio stream.

After the build, run the browser-backed acceptance smoke against the local multi-page fixture. It runs Lighthouse, rendered structured-data validation, and Unlighthouse, so it requires Chrome and can take several minutes:

npm run smoke:browser

To install the built checkout as a local global npm package:

npm install --global .

This installs the agenticseo-mcp executable on PATH. It waits for an MCP client on stdio rather than providing an interactive prompt.

Tools

MCP workflow and response levels

AgenticSEO exposes three response levels so clients can build an SEO backlog without loading a full report:

1. Initial audit result — audit tools return visible compact JSON plus matching structuredContent. Use the report-wide summary, compact findings, bounded tool-specific data, coverage when applicable, resourceUri, and next.primary to start prioritization.

2. Backlog-complete compact report — agentseo://reports/{runId}/summary.json and get_report return diversity-first compact rows. After filters, the highest-ranked representative for each sourceId appears before repeated occurrences. summary.json is exactly the first page of the default get_report view; custom filters change pagination totals, not report-wide summary counts.

3. Selected finding detail — get_finding returns one finding's exact URL, complete evidence and source interpretation, normalization explanation, nullable remediation, bounded provider detail, audit error information, and explicit human-input guidance when business intent is required. Its primary action retrieves same-source siblings and excludes the selected occurrence (and, when useful, its page).

Every compact success response is serialized as valid compact JSON in visible MCP text and mirrored in schema-validated structuredContent. The public DTO is measured against a hard 7,600-byte UTF-8 budget. limit is a requested maximum, defaulting to 10 and capped at 25; if the budget admits fewer complete rows, the result includes truncation: { "reason": "byte_budget", "requested": ..., "returned": ..., "budgetBytes": 7600 }. Never assume the requested limit was fully returned; advance using next.primary.arguments or pagination.nextOffset, based on the actual returned count.

Compact finding rows are triage records, not full remediation records. They include id, sourceId, bounded title, normalized status, area, occurrence/page counts, optional display value and quantified impact, an optional short source-backed suggestedAction, a bounded target with a stable page.ref/displayUrl/truncated marker, and drillDown containing only runId and findingId. Full evidence belongs in get_finding. Current area values are technical_seo, content_metadata, structured_data, performance, indexing, and search_analytics. Status unassessed identifies provider execution failures and is excluded from error/warning issue triage.

The public DTO remains schema 2.0.0: this removal of inferred classification fields is a breaking pre-release contract correction rather than a version increment. Persisted canonical reports remain schema 1.0.0.

Every successful initial result and first report page includes resourceUri for the compact summary and fullReportUri for the complete normalized report, plus a matching resource link. Use next.primary for the main workflow. Use get_audited_pages and get_artifacts for independently filtered and paginated page/artifact retrieval; use fullReportUri only when compact pages and finding detail are insufficient.

For crawls, trust the reported coverage provenance. run_unlighthouse accepts urls as relative routes or same-origin HTTP(S) crawl seeds, rejects credential-bearing, secret-bearing, unsupported-protocol, duplicate, and cross-origin entries before browser work starts, and enforces maxPages across seeded and link-discovered routes. The first seed is the crawl entry page, and all seeds are queued before page-discovered links. Seeded mode disables sitemap discovery so sitemap entries cannot consume the limit ahead of requested seeds; internal-link crawling remains enabled. It omits page arrays from compact data; use get_audited_pages for exact URLs and page scores.

Configuration

Set environment variables on the MCP server process:

The Search Console principal needs read access to the requested URL-prefix or domain property. The server requests only https://www.googleapis.com/auth/webmasters.readonly.

Report-root precedence is: (1) explicit SEO_MCP_OUTPUT_DIR; (2) the first usable local workspace root supplied by a negotiated legacy client; (3) .seo-mcp/reports under the server working directory. MCP 2026-07-28 requests never invoke the deprecated roots exchange. Relative explicit paths resolve from the server working directory. Public tool results expose agentseo:// resource URIs, never absolute local paths.

MCP Inspector

Build first, then start the official Inspector with the local server command:

npx @modelcontextprotocol/inspector node C:\absolute\path\to\agenticseo-mcp\dist\cli.js

The Inspector should list all ten tools, including read-only get_report, get_finding, get_audited_pages, and get_artifacts, plus the agentseo-summary and agentseo-report resource templates. The server supplies the compact workflow instructions through whichever negotiated protocol era the Inspector uses: initial result, diversity-first report pages, independent page/artifact retrieval, then selected finding detail. This follows the official MCP Inspector local-server pattern.

OpenCode

Add a local server to opencode.json and replace the paths. OpenCode resolves the credential values from the environment of the process that launches it:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agenticseo": {
      "type": "local",
      "command": [
        "node",
        "C:\\absolute\\path\\to\\agenticseo-mcp\\dist\\cli.js"
      ],
      "enabled": true,
      "environment": {
        "SEO_MCP_OUTPUT_DIR": "C:\\absolute\\path\\to\\reports",
        "GOOGLE_APPLICATION_CREDENTIALS": "{env:GOOGLE_APPLICATION_CREDENTIALS}",
        "CRUX_API_KEY": "{env:CRUX_API_KEY}"
      }
    }
  }
}

Set those environment variables before launching OpenCode. Omit credential entries for tools you do not use; never put a real key in opencode.json. The structure matches OpenCode's current local MCP configuration and environment-variable substitution.

Experimental Codex MCP 2026-07-28 canary

Codex's modern MCP path is experimental and should not replace the default configuration yet. Maintainers can opt in with the host's mcp_2026_07_28 feature and set CODEX_MCP_PROTOCOL_VERSION=2026-07-28; also set an explicit SEO_MCP_OUTPUT_DIR. This canary is separate from normal client setup and is not a claim of production host validation. If it regresses, disable the feature/marker; the same AgentSEO binary then remains available through legacy negotiation. Roll back the package only if a failure also affects the default legacy path.

Example calls

The examples below show tool argument objects. MCP clients generate the surrounding JSON-RPC request.

// One-page production lab audit (the default mode)
{ "url": "http://localhost:3000/pricing", "device": "mobile", "mode": "production" }

// Site-wide audit. URLs are prioritized same-origin crawl seeds; links discovered
// from those pages fill the remaining maxPages capacity.
{
  "url": "https://example.com/",
  "device": "mobile",
  "mode": "production",
  "maxPages": 50,
  "urls": ["/pricing", "https://example.com/docs/getting-started"],
  "includePaths": ["/docs/**"],
  "excludePaths": ["/docs/archive/**"]
}

// Development keeps SEO findings but suppresses performance findings, scores, and metrics.
// Prefer a production build + mode "production" when you need performance (dev servers add noise).
{ "url": "http://localhost:3000/pricing", "mode": "development" }

// Backlog-complete, diversity-first report page after receiving a run ID.
// limit is a requested maximum; follow next.primary or pagination.nextOffset.
{ "runId": 12, "statuses": ["error", "warning"], "area": "performance", "offset": 0, "limit": 10 }
// Retrieve Lighthouse audits that could not execute; these do not enter error/warning issue triage.
{ "runId": 12, "statuses": ["unassessed"], "offset": 0, "limit": 10 }
// Prefer a stable page reference from a compact row over an exact page URL filter.
{ "runId": 12, "pageRef": "page-0123456789abcdef", "offset": 0, "limit": 10 }
// Retrieve exact crawl pages and registered artifacts independently.
{ "runId": 12, "status": "failed", "offset": 0, "limit": 10 }
{ "runId": 12, "mimeType": "application/json", "offset": 0, "limit": 10 }
// Selected-finding detail, then same-source sibling navigation via next.primary.
{ "runId": 12, "findingId": "finding-example-0001" }

// Search Analytics; dates default to the latest 28 complete Pacific-time days
{
  "property": "sc-domain:example.com",
  "secondaryDimensions": ["query", "device"],
  "filters": {
    "country": { "value": "usa", "operator": "equals" }
  },
  "rowLimit": 1000
}

// URL Inspection (last-known Google state, not live)
{
  "property": "https://example.com/",
  "inspectionUrl": "https://example.com/products/widget"
}

// Exact URL-level field data; no origin fallback
{
  "url": "https://example.com/products/widget",
  "formFactor": "phone"
}

// Validate proposed JSON-LD before deployment
{
  "markup": "{\"@context\":\"https://schema.org\",\"@type\":\"Article\",\"headline\":\"Example\"}",
  "format": "json_ld"
}

Representative outputs

Each successful call returns compact JSON in visible MCP text, the same public DTO in structuredContent, and a compact-summary resource link when the result carries resourceUri. Public results contain report identity, execution status, report-wide summary where applicable, bounded tool data, highlights/coverage where applicable, compact findings, pagination, errors/limitations, and next.primary. Saved summary.json contains the first default get_report page; saved report.json contains complete canonical findings, normalization rules, and provider artifacts. Measured values and provider verdicts vary by call.

A compact initial audit result looks like this (fields not relevant to the example are omitted). The first rows show diversity-first ordering: different sourceId representatives precede repeated occurrences.

{
  "schemaVersion": "2.0.0",
  "runId": 12,
  "executionStatus": "success",
  "summary": {
    "total": 7,
    "error": 3,
    "warning": 4,
    "info": 0,
    "passed": 0,
    "notApplicable": 0,
    "unassessed": 0,
    "areaCounts": { "technical_seo": 1, "content_metadata": 2, "structured_data": 0, "performance": 4, "indexing": 0, "search_analytics": 0 }
  },
  "findings": [
    {
      "id": "finding-example-0001",
      "sourceId": "largest-contentful-paint",
      "title": "Largest Contentful Paint element rendered late",
      "status": "error",
      "area": "performance",
      "occurrenceCount": 1,
      "affectedPageCount": 1,
      "displayValue": "4.2 s",
      "quantifiedImpact": { "value": 1200, "unit": "ms", "label": "Estimated time savings" },
      "target": { "kind": "document", "page": { "ref": "page-0123456789abcdef", "displayUrl": "https://example.com/pricing", "truncated": false } },
      "drillDown": { "runId": 12, "findingId": "finding-example-0001" }
    },
    {
      "id": "finding-example-0002",
      "sourceId": "missing-image-alt",
      "title": "Images are missing alternative text",
      "status": "warning",
      "area": "content_metadata",
      "occurrenceCount": 3,
      "affectedPageCount": 2,
      "suggestedAction": "Add concise alternative text to each informative image.",
      "target": { "kind": "element", "page": { "ref": "page-fedcba9876543210", "displayUrl": "https://example.com/docs", "truncated": false } },
      "drillDown": { "runId": 12, "findingId": "finding-example-0002" }
    }
  ],
  "pagination": { "offset": 0, "limit": 10, "returned": 2, "total": 7, "hasMore": true, "nextOffset": 2 },
  "resourceUri": "agentseo://reports/12/summary.json",
  "fullReportUri": "agentseo://reports/12/report.json",
  "next": { "primary": { "tool": "get_report", "description": "Retrieve the next compact page using the same deterministic filters.", "arguments": { "runId": 12, "offset": 2, "limit": 10 } }, "optional": [] }
}

If the requested maximum cannot fit in 7,600 UTF-8 bytes, the result remains valid JSON and reports the fallback explicitly:

"truncation": { "reason": "byte_budget", "requested": 10, "returned": 8, "budgetBytes": 7600 }

A later get_report page keeps only the page identity, findings, pagination, truncation when applicable, and next.primary; the report-wide summary, highlights, coverage, and resource URIs appear only at offset zero. get_report uses the same compact row shape and stable page references. get_finding then resolves the exact URL and full evidence for one row, with next.primary configured for same-source sibling navigation.

get_audited_pages and get_artifacts are independent read-only streams:

{ "schemaVersion": "2.0.0", "runId": 12, "applicability": "applicable", "pages": [{ "page": { "ref": "page-0123456789abcdef", "displayUrl": "https://example.com/pricing", "truncated": false }, "url": "https://example.com/pricing", "status": "success", "seoScore": 0.92, "performanceScore": 0.81, "findingCount": 2 }], "pagination": { "offset": 0, "limit": 10, "returned": 1, "total": 1, "hasMore": false, "nextOffset": null }, "resourceUri": "agentseo://reports/12/summary.json", "fullReportUri": "agentseo://reports/12/report.json", "next": { "primary": null, "optional": [] } }

{ "schemaVersion": "2.0.0", "runId": 12, "artifacts": [{ "name": "lighthouse.json", "mimeType": "application/json", "resourceUri": "agentseo://reports/12/artifacts/lighthouse.json" }], "pagination": { "offset": 0, "limit": 10, "returned": 1, "total": 1, "hasMore": false, "nextOffset": null }, "resourceUri": "agentseo://reports/12/summary.json", "fullReportUri": "agentseo://reports/12/report.json", "next": { "primary": null, "optional": [] } }

The illustrative excerpts below show the tool-specific structuredContent.data shape.

run_lighthouse:

{
  "kind": "lighthouse",
  "requestedUrl": "https://example.com/",
  "finalUrl": "https://example.com/",
  "device": "mobile",
  "labData": true,
  "mode": "production",
  "categoryScores": { "seo": 0.92, "performance": 0.81 },
  "metrics": [
    {
      "id": "largest-contentful-paint",
      "title": "Largest Contentful Paint",
      "numericValue": 2100,
      "displayValue": "2.1 s",
      "unit": "millisecond",
      "score": 0.91
    }
  ]
}

run_unlighthouse (page records are retrieved with get_audited_pages):

{
  "kind": "unlighthouse",
  "siteUrl": "https://example.com/",
  "device": "mobile",
  "mode": "production",
  "maxPages": 50,
  "discoveryMode": "sitemap_and_links",
  "explicitUrlCount": 2,
  "explicitUrls": ["https://example.com/docs/", "https://example.com/pricing"],
  "explicitUrlsTruncated": false
}

query_search_analytics:

{
  "kind": "search_analytics",
  "property": "sc-domain:example.com",
  "dateRange": { "startDate": "2026-06-01", "endDate": "2026-06-28" },
  "dimensions": ["page", "query", "device"],
  "totalRows": 1,
  "rowsTruncated": false,
  "rows": [
    {
      "page": "https://example.com/products/widget",
      "dimensions": {
        "page": "https://example.com/products/widget",
        "query": "example widget",
        "device": "MOBILE"
      },
      "clicks": 42,
      "impressions": 1000,
      "ctr": 0.042,
      "position": 8.4
    }
  ]
}

inspect_search_console_url:

{
  "kind": "url_inspection",
  "property": "https://example.com/",
  "inspectionUrl": "https://example.com/products/widget",
  "indexStatus": {
    "verdict": "PASS",
    "coverageState": "Submitted and indexed",
    "robotsTxtState": "ALLOWED"
  },
  "richResults": [
    { "richResultType": "Product snippets", "itemCount": 1 }
  ],
  "richResultsVerdict": "PASS"
}

query_crux:

{
  "kind": "crux",
  "granularity": "url",
  "subject": "https://example.com/products/widget",
  "formFactor": "phone",
  "collectionPeriod": { "firstDate": "2026-06-01", "lastDate": "2026-06-28" },
  "metrics": [
    {
      "id": "LCP",
      "p75": 2400,
      "unit": "milliseconds",
      "rating": "good"
    }
  ],
  "missingMetrics": ["INP", "CLS"]
}

validate_structured_data:

{
  "kind": "structured_data",
  "sourceKind": "raw_json_ld",
  "subject": "raw-markup:sha256:0123456789abcdef0123",
  "entityTypes": ["Article"],
  "entityCount": 1,
  "outcome": "structured_data_validated",
  "expectedEntityType": null,
  "detectedPageIntent": null
}

Reports

Each invocation atomically allocates the next positive numeric directory:

.seo-mcp/reports/
  1/
    manifest.json
    summary.json
    report.json
    artifacts/
  2/
    manifest.json
    summary.json
    report.json
    artifacts/

Runs are never overwritten and gaps are not reused. summary.json is the immutable compact summary resource and is equivalent to the first default get_report page, including diversity-first backlog findings, report-wide summary/context, coverage, pagination, resource references, and next.primary. report.json contains all canonical findings, including passed and not-applicable checks, report-level normalization rules, and raw/provider artifacts. Inline MCP results contain no more than the requested finding maximum and may contain fewer when the 7,600-byte UTF-8 budget requires explicit byte_budget truncation; the compact row shape stays fixed and pagination advances by the actual returned count. Use get_report for paginated backlog findings, get_audited_pages for exact crawl page records, and get_finding for one finding's full evidence before reading the full resource. Lighthouse source reports, structured-data issue summaries, Search Console responses, Unlighthouse per-page captures, and the static Unlighthouse dashboard are stored under artifacts/ when applicable and are exposed only through manifest-validated resource references rather than embedded in compact payloads.

This repository already ignores .seo-mcp/; add the same rule to each client project that uses the server.

Evidence and safety rules

• An element target always has an actual selector obtained from Lighthouse or verified against the rendered DOM.

• An expectedSelector describes a missing element; it is never presented as an observed element.

• Compact finding rows are triage records: bounded display values and quantified impact support prioritization, while exact URLs, full evidence, interpretation, remediation, and provider payloads stay in get_finding, report.json, or artifacts.

• suggestedAction can be null; AgenticSEO reports available remediation without manufacturing advice when evidence is insufficient.

• Search Console and CrUX evidence stays page-, origin-, or external-level unless the provider explicitly supplies finer evidence.

• humanInput is included only for an explicit business- or user-intent decision and carries the question to ask, a safe recommendation, the reason, and a warning not to invent facts or approved wording.

• API keys, credential-like fields, bearer tokens, private keys, and configured secrets are redacted before logs and report JSON are written.

• Raw markup is represented by a hash in reports and is not copied wholesale into artifacts.

Navigation can still trigger ordinary server-side GET behavior, analytics, or third-party requests on the audited site. “Read-only” means AgenticSEO makes no intentional edits or mutation requests; it cannot guarantee that a website treats every page load as side-effect-free.

Saved provider artifacts can contain public page content and URLs. Protect the report directory accordingly. The local validator is not an official substitute for Google's live Rich Results Test, and Lighthouse/Unlighthouse results are synthetic lab measurements rather than real-user field data.

The bundled Schema.org vocabulary is third-party material distributed under CC BY-SA 3.0; see Third-Party Notices. AgenticSEO's own code is MIT-licensed.

Development

npm run dev
npm run typecheck
npm test
npm run test:coverage
npm run build
npm run smoke:stdio
npm run smoke:browser

Before release, run the static checks, unit/integration tests, production build, legacy and modern stdio smoke lanes (or their aggregate script), and browser-backed smoke. prepublishOnly runs check plus the aggregate stdio smoke. Browser smoke exercises Lighthouse, rendered structured-data validation, Unlighthouse, report retrieval, and resource workflow coverage; it requires Chrome/Chromium and may take several minutes. Inspect the package with npm pack --dry-run before publishing; the package allowlist should exclude reports, test fixtures, scripts, and credentials.

The test fixture under tests/fixtures/site/ contains multiple routes, missing image alt text, weak link text, problematic canonical markup, and incomplete structured data. Google and CrUX tests use injected clients so automated runs do not require credentials or consume quotas.

Documentation

See the overview, getting started guide, and architecture.