<div align="center">

SEOctopus

Your AI's SEO brain. 23 tools. One MCP server.

Stop Googling SEO metrics. Let your AI pull them directly.

<br />

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.

</div>

---

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

Tool	What It Does	Why It's Great
rank_check	Live Google rankings for any keyword	No API key needed — uses stealth Playwright scraping with anti-detection
analytics_overview	Full GA4 dashboard in one call	Sessions, users, bounce rate, top pages, traffic sources — with period comparison
octo_score	0-100 SEO score weighted by actual Google ranking factors	Research-backed weights, letter grades, actionable recommendations

---

The 8 Arms (23 Tools)

Arm 1: Rank Tracking

No API keys required. Uses stealth browser automation with anti-detection.

Tool	What You Get
rank_check	Where your domain ranks for specific keywords (scans top 100)
rank_history	Trend analysis: up, down, or stable over time (stored locally in SQLite)
rank_competitors	Who's ranking above you and why
rank_serp_features	Featured snippets, People Also Ask, knowledge panels, image packs

Arm 2: Google Analytics (GA4)

Requires OAuth2 setup (one-time, 5 minutes).

Tool	What You Get
analytics_overview	Sessions, users, bounce rate, top pages, traffic sources — with comparison periods
analytics_pages	Per-page performance sorted by pageviews, engagement, or conversions
analytics_traffic	Traffic breakdown by source, medium, campaign, or channel
analytics_realtime	Right-now data: active users, current pages, live events

Arm 3: SEO Auditing

Just pass a URL. No setup needed.

Tool	What You Get
audit_page	Full on-page audit: title, meta, headings, images, canonical, OG tags — with scoring
audit_site	BFS crawl of your entire site with issue aggregation (respects robots.txt)
audit_structured_data	JSON-LD validation with required/recommended field checking
audit_content	Word count, Flesch readability, keyword density, heading hierarchy
audit_links	Internal/external link analysis + broken link detection with concurrent checking

Arm 4: Keyword Research

Search Console tools need OAuth2. Suggestions work without it.

Tool	What You Get
keywords_search_console	Your actual keyword performance: clicks, impressions, CTR, avg position
keywords_suggestions	Google Autocomplete + People Also Ask expansion from a seed keyword
keywords_gaps	Quick wins: keywords where you have high impressions but poor position (positions 4-20)
keywords_cluster	Group keywords by topic and infer search intent (informational/transactional/navigational)

Arm 5: Competitive Analysis

Uses Playwright for SERP scraping + Cheerio for page analysis.

Tool	What You Get
competitive_analyze	Side-by-side comparison: word count, headings, images, structured data, load time
competitive_content_gap	Topics and headings your competitors cover that you don't
competitive_serp_share	Your share of SERP real estate vs competitors across a keyword set

Arm 6: Performance & Core Web Vitals

Tool	What You Get
performance_audit	Lighthouse scores: performance, SEO, accessibility, best practices
performance_compare	Run Lighthouse on 2-5 URLs and compare side-by-side
performance_cwv	LCP, INP, CLS with pass/fail ratings against Google's thresholds

Arm 7: OctoScore

Tool	What You Get
octo_score	Weighted 0-100 SEO score with letter grade (A-F) and prioritized recommendations

Arm 8: Reports

Tool	What You Get
octo_report	Full multi-module report in JSON, Markdown, or dark-themed HTML

---

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

<details> <summary><strong>Google Cloud Setup (click to expand)</strong></summary>

1. Go to Google Cloud Console
2. Create a new project (or use existing)
3. Enable Google Analytics Data API and Search Console API
4. Create OAuth2 credentials → Desktop application
5. Download the credentials JSON file
6. Run npx seoctopus auth setup -c credentials.json

</details>

---

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:

Factor	Weight	What It Measures	Why It Matters
Content Quality	25%	Word count, readability, depth	Google's #1 ranking signal
Core Web Vitals	15%	LCP, INP, CLS	Direct ranking factor since 2021
Title Optimization	12%	Length, keyword placement	Highest CTR impact element
Mobile Friendly	10%	Viewport, responsive design	60%+ of searches are mobile
User Engagement	10%	Bounce rate, time on page	Behavioral signals Google tracks
Backlinks	8%	External links pointing in	Still a top-3 ranking factor
Link Diversity	7%	Internal/external link mix	Healthy sites have balanced links
E-E-A-T	5%	Author, citations, trust	Critical for YMYL content
Freshness	5%	Last modified, publish date	Google rewards recently updated content
Topical Authority	3%	Heading coverage, semantic depth	Comprehensive content ranks better

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

<details> <summary><strong>All CLI Commands (click to expand)</strong></summary>

# 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]

</details>

---

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

What	Why
TypeScript (ES2022, strict)	Type safety for 23 tool schemas
MCP SDK	Standard protocol for AI tool integration
Playwright	Stealth browser for rank tracking
googleapis	Official GA4 + Search Console client
Lighthouse	Performance auditing (same engine as Chrome DevTools)
Cheerio	Fast HTML parsing for audits
better-sqlite3	Embedded storage, zero config
tsup	Fast builds, dual entry points

---

Comparison: SEOctopus vs The Alternatives

Feature	SEOctopus	Ahrefs	SEMrush	Moz
AI-native (MCP)	Yes	No	No	No
Price	Free	$99/mo	$130/mo	$99/mo
Rank tracking	Yes (stealth scraping)	Yes	Yes	Yes
Google Analytics	Yes (GA4 API)	No	Yes	No
Search Console	Yes (API)	No	Yes	No
Site audit	Yes (crawler)	Yes	Yes	Yes
Core Web Vitals	Yes (Lighthouse)	No	Yes	No
CLI	Yes	No	No	No
Self-hosted	Yes	No	No	No
Open source	Yes	No	No	No

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.

Join The Agentic Advantage

---

Contributing

Found a bug or have an idea? Open an issue. Built something cool with SEOctopus? Open a PR.

License

MIT — Go build something.