Skip to main content

MCP server

Connect SEOLint to your AI client in 2 minutes. The agent scans any URL, remembers every issue across runs, and tells you what to fix next.

Quick start

Get SEOLint running inside your AI client in three steps. The whole flow takes about two minutes.

1

Run the connect command

Run this in any terminal. No API key needed up front — the command opens your browser to sign in.

bash
npx -y seolint-mcp connect claude-code

Replace claude-code with your client: claude-desktop, cursor, windsurf, or vscode.

2

Approve in your browser

A browser window opens to seolint.dev/cli-auth. Sign in if needed, then click Approve seolint-mcp on this device. The terminal automatically receives your API key and writes it to the right config file.

3

Restart your client and ask the agent

Quit and reopen your AI client (a Reload Window doesn't pick up the new MCP server). Then ask:

"What should I do next to improve the SEO on mysite.com?"

The agent will call next_action first, then scan_website if needed. From here, the agent decides which tools to call based on the task.

Installation

The connect command in Quick start handles install + auth in one go. If you prefer to set up the config file yourself, pick your AI client below and follow the manual setup.

Current host support

Claude Code, Claude Desktop, Cursor, Windsurf and VS Code (with the MCP extension) all use the same SEOLint MCP server. The only difference is where each one stores its config file.

One command — adds the server, sets the env var, and writes the config for you.

bash
claude mcp add seolint \
  --env SEOLINT_API_KEY=<your_key> \
  -- npx -y seolint-mcp

Restart Claude Code afterwards. Verify with `npx -y seolint-mcp doctor`.

Verify with doctor

After saving your config, run npx -y seolint-mcp doctor to check the env var, API reachability, key validity, subscription, and quota in one shot.

Authentication

The MCP server authenticates with a single API key per account, passed as the SEOLINT_API_KEY environment variable in your MCP client config. The same key works across every client, the REST API, and the CLI — scans are unified under one user, so memory is shared everywhere.

Use connect for the easy path

The connect command in Quick start opens a browser, you click Approve, and your API key is written into your client config automatically. No copying, no JSON editing. Use that whenever possible — manual setup is documented below as a fallback.

Environment variables

NameTypeDescription
SEOLINT_API_KEYstringYour API key from seolint.dev/api. Required by every command.
SEOLINT_API_URLstringOverride the API base URL. Defaults to https://seolint.dev.
Set the env var inside your MCP client config — not your shell. GUI apps don't inherit shell env. After saving, fully quit and reopen the client.

Rate limits

Limits are based on your plan's monthly scan quota. There's no per-second rate limit — scans naturally cap concurrent volume because each one takes 15–45 seconds.

PlanOn-demand scans / monthConcurrent
Free preview11
SEOLint / $791005
CustomNegotiatedNegotiated

Backoff guidance

When the monthly cap is reached, the API returns HTTP 429 with a Retry-After header set to seconds remaining until next month. Well-behaved MCP clients respect this and surface the wait time to the user instead of retrying.

MCP tools reference

The server registers the following 12 tools with your AI assistant. The agent decides which to call automatically based on your prompt — these descriptions are what the agent sees.

scan_websitecore

Run a full scan and label issues as NEW, PERSISTING or REGRESSED based on prior scans of the same URL. The single most important tool — does scanning, history diffing, and recurring tracking in one call.

Parameters

NameTypeDescription
urlstringFull URL to scan, e.g. https://example.com

Returns

Markdown report with scan_id, issue counts, scan memory block, per-issue fix instructions.

next_actioncore

The 'what should I do next' oracle. Returns ONE concrete next action grounded in scan history, memory, and site profile — including 'wait and re-scan in N days' when nothing needs doing right now.

Parameters

NameTypeDescription
urlstringURL to get a recommendation for

Returns

Markdown card with the recommendation, reasoning, confidence level, and a Copy fix prompt action.

get_open_issuescore

Return the unresolved issues for a URL based on the latest scan — without running a new scan. Use this for a flat actionable list.

Parameters

NameTypeDescription
urlstringURL whose open issues you want

Returns

Markdown list of open issues plus any regressed-from-fixed.

get_site_statuscore

High-level memory picture: trend (improving / degrading / stable), recurring patterns, days since last scan, rescan recommendation. Use for 'how is this site doing?' questions.

Parameters

NameTypeDescription
urlstringURL to check

Returns

Markdown summary with trend label and rescan recommendation.

get_site_intelligencecore

Full intelligence for a domain: ICP, sitemap structure and gaps, cross-page template issues, scan coverage. Call at the start of any SEO session to understand the site before diving into individual pages.

Parameters

NameTypeDescription
domainstringDomain to analyze, e.g. example.com (no protocol)

Returns

Markdown brief covering site profile, sitemap, cross-page patterns and coverage.

list_my_sitescore

List every URL you have scanned with the latest scan summary per site.

Parameters

No parameters.

Returns

Markdown table sorted by last-scanned, with rescan flags.

mark_issues_fixedcore

Mark issues as fixed after the user confirms. If a previously fixed issue reappeared, the resurface count is incremented so the system learns it keeps recurring.

Parameters

NameTypeDescription
scan_idstringScan UUID containing the issues
issue_idsstring[]Issue IDs to mark fixed

Returns

Confirmation message + which IDs had previously been fixed.

dismiss_issuescore

Dismiss issues as false positives or intentional design choices. Dismissed issues are hidden from future scans and persist across runs.

Parameters

NameTypeDescription
scan_idstringScan UUID containing the issues
issue_idsstring[]Issue IDs to dismiss
reasonstringWhy these are being dismissed

Returns

Confirmation message.

get_scanutil

Fetch a previous scan by ID. Useful when scan_website timed out and you want to retrieve the result later.

Parameters

NameTypeDescription
scanIdstringThe scan UUID returned by scan_website

Returns

Markdown report (or status string if still pending).

cancel_scanutil

Cancel a scan that is still pending. Escape hatch when scan_website is taking too long or the wrong URL was scanned.

Parameters

NameTypeDescription
scanIdstringThe scan UUID to cancel

Returns

Status message. No effect on scans already complete, errored or cancelled.

get_site_historyutil

Scan history plus resolved/dismissed/recurring state for a URL. Call this before starting any fix session.

Parameters

NameTypeDescription
urlstringURL whose history you want

Returns

Markdown timeline with full issue lifecycle.

undismiss_issuesutil

Un-dismiss previously dismissed issues so they appear as open again.

Parameters

NameTypeDescription
scan_idstringScan UUID (used to identify the URL)
issue_idsstring[]Issue IDs to un-dismiss

Returns

Confirmation message.

CLI reference

The seolint-mcp npm package includes a CLI for setup, validation, and running the MCP server. Most users only need connect and doctor.

CommandDescription
npx -y seolint-mcp connect [host]Browser-based sign-in. Opens seolint.dev, you click Approve, the API key is written into the host's MCP config automatically. Recommended.
npx -y seolint-mcp doctorValidate your setup end-to-end: env var, API reachability, key validity, subscription, quota. Colored ✅/⚠️/❌ output.
npx -y seolint-mcp init [host]Write the MCP config file for [host] using SEOLINT_API_KEY from your shell. Merges with existing servers, backs up the original.
npx -y seolint-mcp upgrade [host]Re-run init for the host and report the installed package version.
npx -y seolint-mcpDefault mode — runs as the MCP server over stdio. Used by your MCP client, not by you directly.
npx -y seolint-mcp --versionPrint the installed package version.

Scan memory

Memory is what makes SEOLint different from a one-shot scanner. Every scan is compared against history, and every issue is annotated with one of three states.

NEW

First time we've seen this issue on this URL.

PERSISTING

Was in the previous scan, still not fixed.

REGRESSED

Was marked fixed before, came back.

When the agent calls mark_issues_fixed after applying a fix, SEOLint records the resolution. If the same issue ever resurfaces, the resurface count is incremented — over time the system learns which fixes are flaky and which stick. Use dismiss_issues with a reason to permanently silence false positives.

Troubleshooting

Common issues encountered when connecting the MCP server. When something feels wrong, run npx -y seolint-mcp doctor first — it covers 90% of setup problems.

"API key required" — but I set it
The env var must live in your MCP client config, not your shell. Different clients store config in different files (see Installation above). After editing, fully quit and reopen the client — Reload Window doesn't pick up env changes.
Tool calls return 401 Invalid API key
The key has been rotated or revoked. Run `npx -y seolint-mcp connect [host]` to refresh, or generate a new key in your dashboard and update the config manually.
Scans are slow or hanging
A typical scan takes 15–45 seconds (browser render + Core Web Vitals + AI analysis). If a scan exceeds 60 seconds, the MCP client surfaces a timeout with the scan_id. Call get_scan(scan_id) later or cancel_scan(scan_id) to abort.
HTTP 429 — Scan limit reached
You've hit your monthly quota. Upgrade your plan to lift the cap immediately, or wait until the 1st of next month for the counter to reset. The Retry-After header tells you exactly how long.
doctor reports the API is unreachable
Check your network, any corporate proxy, and that https://seolint.dev is reachable from your machine.

FAQ

How do I get an API key?
The easiest way is `npx -y seolint-mcp connect claude-code` (or your preferred host). It opens a browser, you click Approve, and the key is written to your config automatically. Or visit seolint.dev/api to copy a key manually.
Where do I put SEOLINT_API_KEY?
In your MCP client config — not your shell. The connect command handles this for you. If you're doing it manually, see Installation for the file path per host.
Can I use SEOLint with multiple AI clients at once?
Yes. The same API key works across Claude Code, Claude Desktop, Cursor, Windsurf, VS Code — and the REST API and CLI. All scans share the same memory, so an issue you mark fixed in one client is gone everywhere.
How does scan memory work across runs?
SEOLint tracks every issue ever found per URL. On every scan, issues are labeled NEW, PERSISTING or REGRESSED. Calling mark_issues_fixed records the resolution, and the resurface count increments if the same issue comes back later — so the agent learns which fixes are flaky.

Ready to connect?

One command. Browser opens. You click Approve. Done.

bash
npx -y seolint-mcp connect claude-code

Or grab an API key manually →