CiteStat MCP Server Reference

MCP (Model Context Protocol) server for AI agent integration with CiteStat.

Setup

Install the CLI, then use it as an MCP server:

curl -fsSL https://citestat.com/install.sh | sh
aiseo login --key <your-api-key>

Add to .claude/settings.json:

{
  "mcpServers": {
    "aiseo": { "command": "aiseo", "args": ["mcp"] }
  }
}

Option 2: MCP HTTP (Streamable HTTP)

Connect directly to the hosted MCP endpoint (no local install needed):

URL: https://citestat.com/api/mcp
Auth: Authorization: Bearer <api-key>
Transport: Streamable HTTP (POST/GET/DELETE)

Credits (HTTP only). A scan over MCP costs what POST /api/scan costs: seo_scan and seo_report 1 credit, seo_compare 1 credit per URL. Each scan is saved to your account (its history, its report link) — that saved scan is the credit. A call your remaining credits for today cannot cover is refused before it scans, with isError: true and the credits left; the other tools cost nothing. Each tool call appears in the dashboard's API usage as /api/mcp/<tool>. The local stdio server (aiseo mcp) is not metered.

Option 3: Bun (development)

{
  "mcpServers": {
    "aiseo": {
      "command": "bun",
      "args": ["run", "/path/to/aiseo/apps/mcp/index.ts"]
    }
  }
}

Technical Details

PropertyValue
Server nameaiseo
Version1.0.0
Transportstdio (CLI), Streamable HTTP (API)
SDK@modelcontextprotocol/sdk
RuntimeBun

Tools

seo_scan

Run a full SEO audit on a URL. Returns score, grade, and categorized findings.

Parameters:

NameTypeRequiredDescription
urlstring (URL)YesURL to audit
skipPerfbooleanNoSkip PageSpeed Insights API checks (faster)

Returns: Text summary with:

  • Overall score (0-100) and grade (A-F) — the same headline POST /api/scan returns for that URL (one pipeline, packages/core/seo-scan.ts): the rules-engine total, minus the thin-content deduction; see docs/api.md "How totalScore is derived"
  • Rules checked: <n> of <m> — how many of the engine's rules the scan evaluated (rules for a stack the page does not run — WordPress, Nginx, Cloudflare, Laravel — and, with skipPerf, the Core Web Vitals rules are not run)
  • Category scores: On-Page, Performance, Technical, Structured Data, GEO & AI, Content — a category that measured nothing (Performance without PageSpeed) prints "N/A (not measured)", not 0
  • Critical issues list with details, then high priority, including rules-engine findings

Example prompt: "Audit the SEO of https://erpfit.com"

Checks performed:

  • On-Page: title, meta description, headings, canonical, viewport, images
  • Technical: HTTPS, robots.txt, sitemap, security headers, redirects
  • Structured Data: Schema.org JSON-LD, Open Graph, Twitter Cards
  • Performance: Core Web Vitals via PageSpeed Insights (LCP, CLS, FCP, TTFB)
  • GEO/AI: llms.txt, AI crawler access, citability signals, FAQ schema
  • Content: word count, internal links, text-to-HTML ratio, E-E-A-T signals
  • Rules Engine: the same rule files POST /api/scan runs (the live count is /api/health → checker.rules)

seo_render

Simulate how AI search engines (Google AI Overviews, ChatGPT, Perplexity) extract and cite content from a page.

Parameters:

NameTypeRequiredDescription
urlstring (URL)YesURL to analyze

Returns: Text summary with:

  • Overall citability score (0-100)
  • Passage count and top 5 passages ranked by citability
  • Semantic HTML score
  • Freshness signals
  • Author detection (name + Schema.org markup)
  • AI Overview simulation (best passage + citation preview)
  • Featured snippet type detection
  • People Also Ask questions extracted

Example prompt: "How well would AI search engines cite content from https://sieuthicafe.vn?"


seo_compare

Compare SEO scores across multiple URLs side-by-side.

Parameters:

NameTypeRequiredDescription
urlsstring[] (2-5 URLs)YesURLs to compare
skipPerfbooleanNoSkip PageSpeed checks

Returns: Ranked comparison with:

  • Each URL sorted by total score (highest first)
  • Grade and total score per URL — each URL runs the same pipeline as seo_scan, so a number here matches the number POST /api/scan gives for that URL
  • Category breakdown for each URL

Example prompt: "Compare SEO of https://erpfit.com vs https://sieuthicafe.vn vs https://pbnc.vn"


seo_report

Run an audit and save the results to the database. Returns permanent report URLs.

Parameters:

NameTypeRequiredDescription
urlstring (URL)YesURL to audit
skipPerfbooleanNoSkip PageSpeed checks

Returns: Text with:

  • Score and grade — the same headline POST /api/scan returns for that URL (one pipeline)
  • HTML report URL: the share link https://citestat.com/api/report/p/{token} (opens without a login)
  • PDF report URL: https://citestat.com/api/report/p/{token}/pdf
  • The scan is saved to the API key's account (HTTP endpoint); stdio runs have no account
  • Scan ID for later retrieval

Example prompt: "Generate a full SEO report for https://tamyenthinh.com and give me the PDF link"


seo_schedule

Re-scan one of your domains on a schedule (Agency plan — SCHED-01). Runs for the account of the API key (HTTP MCP only; the local stdio server has no account and refuses). The first scan runs within 15 minutes, then once per cadence; each scan uses 1 credit and lands in the domain's history. When a scan scores 5+ points below the previous one, the account's users get an e-mail. Free-form cron is refused so a schedule cannot hammer a site.

Parameters:

NameTypeRequiredDescription
domainstringYesDomain name (e.g. example.com)
cadencedaily \weekly \monthly \offNoHow often (default weekly); off stops it
cronstringNoDeprecated: only @daily, @weekly, @monthly are accepted
emailstring (email)NoIgnored: alerts go to the account's own users only

Returns: the cadence and when the first scan runs, or why it was refused (plan, limit of 50 per account).

Example prompt: "Re-scan pbnc.vn every week and tell me when the score drops"

The same setting is on the dashboard: Domains → a domain → Recurring scan.


seo_content_audit

Deep content quality analysis with E-E-A-T signals, readability, and detailed fix suggestions.

Parameters:

NameTypeRequiredDescription
urlstring (URL)YesURL to audit content quality
keyphrasestringNoTarget keyphrase for density/placement checks

Returns: Content score (0-100), content type/language/word count, section scores, and top issues with actionable suggestions.

Example prompt: "Audit the content quality of https://sieuthicafe.vn/blog/pour-over"


seo_performance

Check Core Web Vitals and Lighthouse performance for a domain.

Parameters:

NameTypeRequiredDescription
domainstringYesDomain to check (e.g. example.com)

Returns: Performance score, CWV metrics (LCP, CLS, FCP, TTFB), and issues with fix recommendations.

Example prompt: "Check the performance of erpfit.com"


seo_opportunities

Find SEO growth opportunities from Google Search Console data (requires GSC connection).

Parameters:

NameTypeRequiredDescription
domainstringYesDomain to find opportunities for

Returns: Striking-distance keywords, CTR gaps, zero-click queries, and cannibalization issues — minimum volumes scale to the site's size, so a small site gets its own top items; each item names its targetPage (the page to fix) (see GET /api/sites/:domain/opportunities in api.md). Requires GSC OAuth connection via the dashboard.

Example prompt: "Find SEO opportunities for sieuthicafe.vn"


seo_trend

Compare two scans to see score, category, and finding changes over time.

Parameters:

NameTypeRequiredDescription
scanId1stringYesFirst (older) scan ID
scanId2stringYesSecond (newer) scan ID

Returns: Score delta, grade change, per-category changes, new issues, and resolved issues. Over the HTTP endpoint both scans must belong to your API key's account (another account's scan id reads as "Scan not found", as GET /api/scans/:id/diff); a card skipped in either scan (e.g. Performance with skipPerf) is not listed as a change.

Example prompt: "Compare scan cm1abc with scan cm2xyz to see what changed"


seo_metrics

Get scan history and score trend for a domain.

Parameters:

NameTypeRequiredDescription
domainstringYesDomain to get metrics for
limitnumberNoNumber of recent scans (default: 10)

Returns: Latest score, trend direction, and chronological scan history with IDs.

Example prompt: "Show me the SEO score history for pbnc.vn"


seo_submit

Submit URLs to search engines via IndexNow protocol (Bing, Yandex, Seznam, Naver, Yep, Amazon, Internet Archive — one submission is shared with all of them; it asks for a crawl, it does not guarantee indexing).

Parameters:

NameTypeRequiredDescription
urlsstring[] (1-100 URLs)YesURLs to submit — all on ONE exact host; www.example.com and example.com are two hosts to IndexNow, so a mixed list is refused before the POST
keystringNoIndexNow key (auto-generated if not provided)

Returns: Submission status and key publication instructions.

Example prompt: "Submit https://erpfit.com/blog/new-post to search engines via IndexNow"


CiteStat Authority 0–100 plus the link-graph profile, for any domain, from free sources.

Parameters:

NameTypeRequiredDescription
domainstringYesDomain to check (e.g. example.com)
driverstringNoRaw profile source: commoncrawl (default — local link graph only, never the 120 s stream) or openpagerank (needs OPENPAGERANK_API_KEY)

Returns: the Authority score, confidence, components, flags and the sources consulted (same data as GET /api/sites/:domain/authority), then — where the server has the CC DuckDB — harmonic centrality / PageRank ranks, referring-domain count and the top referring domains (strongest first). The production VM carries a slim CC ranks file (BL-SCORE-03): the score uses CC ranks + Cloudflare Radar + blocklists; the referring-domain fields stay empty there (no edges DB on the VM).

Example prompt: "Check the backlink profile of sieuthicafe.vn"


seo_keywords

Keyword ideas from Google or YouTube autocomplete (Vietnam by default), grouped into questions (FAQ / content angles) and other ideas.

Parameters:

NameTypeRequiredDescription
seedstringYesSeed keyword (1–80 characters)
langstringNovi (default) or en
sourcestringNogoogle (default) or youtube
alphabetbooleanNoAlso expand seed a … seed z (26 more queries)

Returns: Question-form ideas and other ideas, with a count of failed upstream queries. Autocomplete shows demand phrasing, not search volume.

Example prompt: "Find keyword ideas for 'máy pha cà phê' in Vietnam"


seo_drift

Detect SEO regressions by comparing a baseline scan against a current scan.

Parameters:

NameTypeRequiredDescription
scanId1stringYesBaseline scan ID
scanId2stringYesCurrent scan ID

Returns: Score change, regressions by category, improvements, new issues, and resolved issues. Over the HTTP endpoint both scans must belong to your API key's account (another account's scan id reads as "Scan not found", as GET /api/scans/:id/diff); a card skipped in either scan (e.g. Performance with skipPerf) is not listed as a change.

Example prompt: "Check for SEO regressions between scan cm1abc (last month) and cm2xyz (today)"


Usage Tips

  1. Quick audit: Use seo_scan for a fast overview with actionable issues
  2. Content deep-dive: Use seo_content_audit for detailed content quality analysis with fix suggestions
  3. AI readiness: Use seo_render to check if content is optimized for AI citation
  4. Competitor analysis: Use seo_compare to benchmark against competitors
  5. Reporting: Use seo_report to generate shareable HTML/PDF reports
  6. Monitoring: Use seo_schedule for weekly/monthly re-scans with score-drop e-mails (Agency) + seo_drift to catch regressions
  7. Performance: Use seo_performance for Core Web Vitals analysis
  8. Authority: Use seo_backlinks for domain authority and referring domain data
  9. Indexing: Use seo_submit to push updated pages to Bing/Yandex via IndexNow
  10. Skip perf for speed: Set skipPerf: true to skip the PageSpeed API call (saves ~3-5s)

Data Sources

  • PageSpeed Insights API — Core Web Vitals field + lab data (free, no key required)
  • CrUX API — Chrome User Experience Report field data (free)
  • Rules Engine — 312+ rules extracted from Google Search Central and Bing Webmaster docs
  • cheerio — HTML parsing for on-page analysis
  • aicli gateway — Multi-model AI for content analysis suggestions