CiteStat MCP Server Reference
MCP (Model Context Protocol) server for AI agent integration with CiteStat.
Setup
Option 1: CiteStat CLI (recommended)
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
| Property | Value |
|---|---|
| Server name | aiseo |
| Version | 1.0.0 |
| Transport | stdio (CLI), Streamable HTTP (API) |
| SDK | @modelcontextprotocol/sdk |
| Runtime | Bun |
Tools
seo_scan
Run a full SEO audit on a URL. Returns score, grade, and categorized findings.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
url | string (URL) | Yes | URL to audit |
skipPerf | boolean | No | Skip PageSpeed Insights API checks (faster) |
Returns: Text summary with:
- Overall score (0-100) and grade (A-F) — the same headline
POST /api/scanreturns for that URL (one pipeline,packages/core/seo-scan.ts): the rules-engine total, minus the thin-content deduction; seedocs/api.md"HowtotalScoreis 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, withskipPerf, 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/scanruns (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:
| Name | Type | Required | Description |
|---|---|---|---|
url | string (URL) | Yes | URL 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:
| Name | Type | Required | Description |
|---|---|---|---|
urls | string[] (2-5 URLs) | Yes | URLs to compare |
skipPerf | boolean | No | Skip 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 numberPOST /api/scangives 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:
| Name | Type | Required | Description |
|---|---|---|---|
url | string (URL) | Yes | URL to audit |
skipPerf | boolean | No | Skip PageSpeed checks |
Returns: Text with:
- Score and grade — the same headline
POST /api/scanreturns 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:
| Name | Type | Required | Description | |||
|---|---|---|---|---|---|---|
domain | string | Yes | Domain name (e.g. example.com) | |||
cadence | daily \ | weekly \ | monthly \ | off | No | How often (default weekly); off stops it |
cron | string | No | Deprecated: only @daily, @weekly, @monthly are accepted | |||
email | string (email) | No | Ignored: 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:
| Name | Type | Required | Description |
|---|---|---|---|
url | string (URL) | Yes | URL to audit content quality |
keyphrase | string | No | Target 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:
| Name | Type | Required | Description |
|---|---|---|---|
domain | string | Yes | Domain 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:
| Name | Type | Required | Description |
|---|---|---|---|
domain | string | Yes | Domain 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:
| Name | Type | Required | Description |
|---|---|---|---|
scanId1 | string | Yes | First (older) scan ID |
scanId2 | string | Yes | Second (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:
| Name | Type | Required | Description |
|---|---|---|---|
domain | string | Yes | Domain to get metrics for |
limit | number | No | Number 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:
| Name | Type | Required | Description |
|---|---|---|---|
urls | string[] (1-100 URLs) | Yes | URLs 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 |
key | string | No | IndexNow 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"
seo_backlinks
CiteStat Authority 0–100 plus the link-graph profile, for any domain, from free sources.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
domain | string | Yes | Domain to check (e.g. example.com) |
driver | string | No | Raw 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:
| Name | Type | Required | Description |
|---|---|---|---|
seed | string | Yes | Seed keyword (1–80 characters) |
lang | string | No | vi (default) or en |
source | string | No | google (default) or youtube |
alphabet | boolean | No | Also 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:
| Name | Type | Required | Description |
|---|---|---|---|
scanId1 | string | Yes | Baseline scan ID |
scanId2 | string | Yes | Current 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
- Quick audit: Use
seo_scanfor a fast overview with actionable issues - Content deep-dive: Use
seo_content_auditfor detailed content quality analysis with fix suggestions - AI readiness: Use
seo_renderto check if content is optimized for AI citation - Competitor analysis: Use
seo_compareto benchmark against competitors - Reporting: Use
seo_reportto generate shareable HTML/PDF reports - Monitoring: Use
seo_schedulefor weekly/monthly re-scans with score-drop e-mails (Agency) +seo_driftto catch regressions - Performance: Use
seo_performancefor Core Web Vitals analysis - Authority: Use
seo_backlinksfor domain authority and referring domain data - Indexing: Use
seo_submitto push updated pages to Bing/Yandex via IndexNow - Skip perf for speed: Set
skipPerf: trueto 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