SEOctopus
Your AI's SEO brain. 23 tools. One MCP server.
Stop Googling SEO metrics. Let your AI pull them directly.
Rank tracking, Google Analytics, site audits, keyword research, competitive analysis, Core Web Vitals, and a research-backed scoring system — all accessible through natural language or CLI.
Why This Exists
Every SEO tool costs $100-300/month. Ahrefs, SEMrush, Moz — they're great, but they're designed for humans clicking dashboards.
SEOctopus is different. It's designed for AI. Your Claude assistant can pull rankings, analytics, and audit data in real-time through MCP — no browser tabs, no copy-pasting, no monthly subscription.
You ask a question. Your AI answers with live data.
You: "Where do we rank for 'best mcp servers' and how's our traffic this month?"
Claude: Let me check... [calls rank_check + analytics_overview]
Rankings:
- "best mcp servers" → #7 (up from #12 last week)
- "mcp server tools" → #3
Traffic (last 28 days):
- Sessions: 4,231 (+18% vs previous period)
- Top source: Organic Search (62%)
- Bounce rate: 34% (good)
If You Only Try 3 Things, Try These
The 8 Arms (23 Tools)
Arm 1: Rank Tracking
No API keys required. Uses stealth browser automation with anti-detection.
Arm 2: Google Analytics (GA4)
Requires OAuth2 setup (one-time, 5 minutes).
Arm 3: SEO Auditing
Just pass a URL. No setup needed.
Arm 4: Keyword Research
Search Console tools need OAuth2. Suggestions work without it.
Arm 5: Competitive Analysis
Uses Playwright for SERP scraping + Cheerio for page analysis.
Arm 6: Performance & Core Web Vitals
Arm 7: OctoScore
Arm 8: Reports
Quick Start (2 Minutes)
# 1. Clone and install
git clone https://github.com/itsjwill/seoctopus.git
cd seoctopus
npm install
# 2. Build
npm run build
# 3. Install browser for rank tracking
npx playwright install chromium
Add to Claude as MCP Server
{
"mcpServers": {
"seoctopus": {
"command": "node",
"args": ["/path/to/seoctopus/dist/index.js"]
}
}
}
That's it. Claude now has 23 SEO tools.
Want Google Analytics + Search Console too?
# One-time OAuth2 setup (requires Google Cloud project)
npx seoctopus auth setup -c /path/to/credentials.json
- Go to Google Cloud Console
- Create a new project (or use existing)
- Enable Google Analytics Data API and Search Console API
- Create OAuth2 credentials → Desktop application
- Download the credentials JSON file
- Run
npx seoctopus auth setup -c credentials.json
Where Should I Start?
Just want to check rankings?
→ No setup needed. rank_check uses stealth browser scraping.
Want the full SEO picture? → Set up Google OAuth2 (5 min) to unlock Analytics + Search Console tools.
Building an SEO monitoring system?
→ Use octo_score + rank_history for automated weekly tracking with trend detection.
Comparing against competitors?
→ competitive_analyze + competitive_content_gap gives you the full picture.
Need a client report?
→ octo_report generates presentation-ready HTML with dark theme.
OctoScore — The SEO Rating System
Not another vanity metric. OctoScore is weighted by what Google actually cares about:
Grades: A (90+) · B (75-89) · C (60-74) · D (40-59) · F (<40)
Each score comes with prioritized recommendations ranked by estimated impact.
CLI Usage
SEOctopus works as a standalone terminal tool too.
# Check where you rank
seoctopus rank check "best seo tools" "mcp server" -d example.com
# Full page audit
seoctopus audit page https://example.com
# Content analysis with keyword targeting
seoctopus audit content https://example.com -k "target keyword"
# Core Web Vitals check
seoctopus perf cwv https://example.com
# Keyword opportunities from Search Console
seoctopus keywords gaps -s https://example.com
# Generate HTML report
seoctopus report https://example.com -f html -o report.html
# Calculate OctoScore
seoctopus score https://example.com -k "target keyword"
# Competitor deep dive
seoctopus compete analyze "target keyword" -u https://yoursite.com
# Rank tracking
seoctopus rank check <keywords...> -d <domain> [-c country] [--device desktop|mobile]
seoctopus rank history -d <domain> [-k keywords...] [--days 30]
# SEO auditing
seoctopus audit page <url>
seoctopus audit site <url> [-p maxPages] [-d depth]
seoctopus audit content <url> [-k keyword]
seoctopus audit links <url> [-e checkExternal]
# Performance
seoctopus perf audit <url> [--device mobile|desktop]
seoctopus perf cwv <url> [-s mobile|desktop]
seoctopus perf compare <url1> <url2> [url3...] [--device mobile|desktop]
# Google Analytics
seoctopus analytics overview -p <propertyId> [--date last28days] [--compare previousPeriod]
seoctopus analytics pages -p <propertyId> [--sort pageviews|engagement|bounceRate|conversions]
seoctopus analytics realtime -p <propertyId>
# Keywords
seoctopus keywords gsc -s <siteUrl> [--sort clicks|impressions|ctr|position]
seoctopus keywords suggest <seed> [-c country]
seoctopus keywords gaps -s <siteUrl> [--min-impressions 100] [--max-position 20]
seoctopus keywords cluster <keyword1> <keyword2> [keyword3...]
# Competitive
seoctopus compete analyze <keyword> [-u yourUrl] [-n numCompetitors]
seoctopus compete gap <yourUrl> <competitorUrl1> [competitorUrl2...]
seoctopus compete share <keyword1> [keyword2...] -d <domain>
# Scoring & Reports
seoctopus score <url> [-k keyword] [-p ga4PropertyId]
seoctopus report <url> [-k keyword] [-f json|markdown|html] [-o outputFile]
# Auth & Config
seoctopus auth setup -c <credentialsFile>
seoctopus auth status
seoctopus config [--set key=value] [--get key]
How It's Built
seoctopus/
├── src/
│ ├── index.ts # MCP server entry (stdio transport)
│ ├── server.ts # 23 tool definitions with Zod schemas
│ ├── cli.ts # Full CLI with Commander
│ ├── auth/google.ts # OAuth2 with auto token refresh
│ ├── data/store.ts # SQLite (WAL mode) for history
│ ├── modules/
│ │ ├── rank-tracker/ # Playwright + anti-detection + SERP parsing
│ │ ├── analytics/ # GA4 Data API + Admin API + Realtime
│ │ ├── auditor/ # On-page, content, links, schema, crawler
│ │ ├── keywords/ # Search Console + autocomplete + clustering
│ │ ├── competitive/ # Competitor analysis + content gaps + SERP share
│ │ └── performance/ # Lighthouse + PageSpeed Insights + CWV
│ ├── scoring/ # OctoScore: weights, grader, recommendations
│ ├── reports/ # JSON, Markdown, HTML (dark theme) formatters
│ └── utils/ # Config (Conf), logging, rate limiter
├── bin/seoctopus.ts # CLI executable entry
├── tsup.config.ts # Dual-entry build (MCP + CLI)
└── package.json
Under the Hood
- Anti-detection SERP scraping — Random user agents, viewport sizes, human-like delays, webdriver spoofing via Playwright
- SQLite with WAL — Concurrent read/write for rank history tracking and trend detection
- OAuth2 token management — Auto-refresh, credential persistence, scoped to read-only
- Rate limiting — Built-in limiter respects Google API quotas
- Lazy module loading — Each tool dynamically imports its module for fast startup
- 3 report formats — JSON for machines, Markdown for docs, HTML with dark theme for presentations
Tech Stack
Comparison: SEOctopus vs The Alternatives
SEOctopus won't replace Ahrefs' backlink index or SEMrush's keyword database. But for real-time SEO data inside your AI workflow — it's the only option.
Development
npm run dev # Watch mode (auto-rebuild on changes)
npm run typecheck # TypeScript strict mode check
npm run lint # ESLint
npm run format # Prettier
npm run test # Vitest
Want to Build Real Projects With AI Tools Like This?
Stop collecting bookmarks. Start shipping.
Join The Agentic Advantage — where builders learn to turn AI tools into income.
Contributing
Found a bug or have an idea? Open an issue. Built something cool with SEOctopus? Open a PR.
License
MIT — Go build something.