SEOctopus Intelligence MCP

<div align="center">

SEOctopus

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

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

MCP Server

Node

TypeScript

License

[Tools]()

[GA4]()

[Search Console]()

<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 track