SEO Perception

npx add-mcp 'https://seoperception.com/mcp'

SEO Perception

Search Console, crawl, and your open SEO to-dos — inside Cursor and Claude.

SEO Perception already stores weekly Search Console facts, the crawl, and Possibilities — a prioritized to-do list for each URL. MCP lets Cursor and Claude read that workspace, draft the next edit, and, with the mcp:possibilities scope, mark those to-dos done or ignored. Tools never call Google.

Start a 7-day trial (MCP included)

Start your 7-day Starter trial — MCP is included. Then:

1. Create your account (Google signup connects Search Console next).
2. Connect Google Search Console, then finish the trial checkout (cancel anytime before it converts).
3. Add a site so we can crawl and store weekly Search Console facts.
4. Wait for stored data, then connect Cursor or Claude (OAuth or a personal token).

Empty tool results usually mean Search Console or a site is not connected yet — not that the MCP endpoint is down.

Hosted endpoint

npx add-mcp 'https://seoperception.com/mcp'

• URL: https://seoperception.com/mcp
• Auth: OAuth Connect when the client supports it, or Bearer <your MCP token>
• Access: Included on the 7-day Starter trial and on paid plans. Start the trial, then manage connections under Account → MCP.

Cursor and Claude can use OAuth (browser consent) when the client supports Connect. You can also create a personal access token under Account → MCP. Each secret is shown once. Store it as SEOPERCEPTION_MCP_TOKEN.

Cursor

Add this to ~/.cursor/mcp.json or the project .cursor/mcp.json (Bearer token path):

{
  "mcpServers": {
    "seo-perception": {
      "url": "https://seoperception.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SEOPERCEPTION_MCP_TOKEN}"
      }
    }
  }
}

Other MCP clients

Claude Desktop, Claude Code, VS Code, and others use the same remote endpoint. If a client only supports local MCP, use that client’s remote or proxy option with the URL and token above.

What the editor is reading

MCP is not a thinner SEO tool. It is the product you already use, opened from Cursor or Claude.

The data

Weekly Search Console facts, the crawl, and page history. Queries stay tied to the URL. MCP reads what is already stored. It does not call Google.

The workspace

The same pages, queries, and evidence you review in SEO Perception, including on the live page with the site overlay.

The to-do list

Possibilities is the prioritized list: what to do, on which URL, and why. seoperception_list_opportunities returns that list. Follow nextCursor until it is null. view: summary is one row per issue type.

Closing a to-do

seoperception_update_possibilities marks existing rows done or ignored. Copy id, typeKey, and pageUrl from a list result. Do not invent ids.

• By id: pass up to 25 issueIds. That applies immediately.
• By issue type: pass issueKey (the typeKey from the list).
• By URL: pass pageUrl. Combine it with issueKey to close one type on one URL.
• Done (completed) can reopen on the next crawl if the check still fails.
• Ignore (ignored_permanent) stays hidden. It requires a reason.
• A type or URL selector returns a preview until confirm is true. More than 25 matches are not applied; pass explicit ids instead.
• Connect requests mcp:read mcp:possibilities. Allow both on the consent screen. A client that asks only for mcp:read can list, not close. Personal tokens stay read-only unless you create one with closing enabled. No recrawl, no new tasks, and no calls to Google.

Data boundary

• MCP never re-queries Google Search Console or URL Inspection.
• Answers use data SEO Perception has already collected for your sites.
• Your MCP client may send returned evidence to its model provider. Treat results as sensitive site analytics.
• After the trial, an active paid plan is required (Starter, Pro, Business, Enterprise).

Available tools

These tools appear in tools/list once your client is connected and your account is entitled (trial or paid).

Tool	Name	What it does
seoperception_list_sites	List sites	List owned websites with stored GSC and crawl freshness.
seoperception_get_site_overview	Site overview	Summarize stored search performance, leading pages, queries, and rank momentum.
seoperception_search_queries	Search queries	Search and filter stored query evidence by content match, position band, impressions, landing page, CTR, and intent. Content filters use stored match rows only.
seoperception_list_opportunities	SEO opportunities	List stored Possibilities. Filter by status, issue type, or URL, or ask for a summary grouped by type.
seoperception_find_cannibalization	Keyword cannibalization	Find stored query conflicts and the deterministic preferred page.
seoperception_find_content_gaps	Content and snippet gaps	Find stored low-CTR, missing-query, title/snippet, question, and refresh opportunities.
seoperception_suggest_internal_links	Internal-link suggestions	Return stored destination and anchor opportunities without crawling or probing URLs.
seoperception_update_possibilities	Close Possibilities	Mark existing Possibilities done or ignored by id, issue type, or URL. Requires the mcp:possibilities scope. Ignore needs a reason and stays hidden.
seoperception_get_page_diagnostics	Page diagnostics	Combine one page’s crawl metadata, stored GSC trends, top queries, and possibilities.
seoperception_find_content_decay	Content decay	Detect sustained stored click and position declines from open refresh-candidate rows. An empty result means none are stored yet.

Example prompts

Prefer observed evidence from tool results over invented recommendations.

• List sites. “List my SEO Perception sites and tell me which data is freshest.”
• Site overview. “Summarize the strongest gains and losses for my site using stored data.”
• Search queries. “Find non-branded queries in positions 5–20 with at least 50 impressions that are missing from their landing page.”
• SEO opportunities. “List my open SEO to-dos. Then mark the ones on /page1/ done after you draft the fix.”
• Keyword cannibalization. “Find keyword cannibalization and recommend which page should be preferred.”
• Content and snippet gaps. “Find the biggest content and snippet gaps, then suggest rewrites that match the losing keywords.”
• Internal-link suggestions. “Suggest internal links and natural anchor text for pages with ranking potential.”
• Close Possibilities. “Mark possibility 42 done. Ignore the missing-meta group on /about/ because that template does not use a meta description.”
• Page diagnostics. “Diagnose /page1/ from crawl state, top queries, and opportunities, then tell me what to rewrite first.”
• Content decay. “Which pages show meaningful content decay?”

Rate limits

• POST /mcp: 60/min per IP before auth, 120/min per token after.
• Tool calls: 30/min per user, token, and site combination.
• Token creation: 5 attempts per user per hour.

Security

Prefer OAuth Connect in Cursor or Claude when the client supports it (browser consent; revoke under Account → MCP). Personal access tokens are for clients that need a Bearer secret such as SEOPERCEPTION_MCP_TOKEN. Never put your SEO Perception login password or a browser session cookie in an MCP client config.

Troubleshooting

• 401: for OAuth, reconnect from the client or revoke and reconnect under Account → MCP; for a personal access token, create a new token and update the env var.
• 403 paid_plan_required: start or resume a Starter trial, or upgrade, then connect with OAuth or create a token.
• 429: wait for the retry time in the response.
• 406: send Accept: application/json, text/event-stream.
• Empty lists usually mean Search Console is not connected, no site is added yet, or stored data is still collecting.

Common questions

What is an SEO MCP server?

An SEO MCP server lets Cursor or Claude read your stored Search Console data, crawl, and open Possibilities, then draft the next edit on a URL.

Is MCP a separate dataset?

No. MCP reads the same weekly Search Console facts, crawl, and Possibilities list you already use in SEO Perception. There is no second copy of your site.

Can an agent mark a to-do done or ignored?

Yes. Connect in Cursor requests mcp:read and mcp:possibilities. Allow both on the consent screen. seoperception_update_possibilities closes existing Possibilities by id, issue type, or URL. Done can come back on the next crawl. Ignore is permanent and needs a reason. A type or URL change previews until confirm is true, and never closes more than 25 rows at once. A client that asks only for mcp:read cannot change anything. A personal access token can close Possibilities only when you enable that while creating it. Existing tokens stay read-only.

Does SEO Perception MCP call Google Search Console live?

No. MCP tools read stored weekly Search Console facts and crawl evidence already collected in SEO Perception. Collection happens in the product sync, not inside the MCP tool call.

Which MCP clients are supported?

Cursor and Claude can connect with OAuth when they support Connect. Any MCP client that can call a remote HTTP endpoint with a Bearer token also works, including VS Code with an MCP extension.

Do I need a paid plan?

Start with a 7-day Starter trial (MCP included). Create an account, start the trial, connect Google Search Console, and add a site so we can store evidence. After the trial, OAuth, personal access tokens, and POST /mcp require an active Starter, Pro, Business, or Enterprise plan.

Guides

This page covers setup, tokens, and the tool catalog. The posts below explain workflows, comparisons, and how to run SEO from Cursor with stored evidence.

• How we use MCP while we build this site
• Building Ted Auto with MCP
• What is an SEO MCP server?
• Google Search Console MCP: live API vs stored evidence
• 7 SEO workflows from Cursor with MCP
• Turn GSC queries into content briefs with MCP
• Find keyword cannibalization with an AI agent and MCP

Next step

Start your 7-day Starter trial (MCP included). Connect Search Console, add a site, wait for stored data, then connect with OAuth or a personal token under Account → MCP.

• View pricing
• Read the docs
• MCP page