# SEOctopus
### Your AI's SEO brain. 23 tools. One MCP server.
**Stop Googling SEO metrics. Let your AI pull them directly.**
[](https://modelcontextprotocol.io)
[](https://nodejs.org)
[](https://www.typescriptlang.org/)
[](LICENSE)
[]()
[]()
[]()
*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
| 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)
```bash
# 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
```json
{
"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?
```bash
# One-time OAuth2 setup (requires Google Cloud project)
npx seoctopus auth setup -c /path/to/credentials.json
```
Google Cloud Setup (click to expand)
1. Go to [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
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`
---
## 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.
```bash
# 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
```
All CLI Commands (click to expand)
```bash
# Rank tracking
seoctopus rank check -d [-c country] [--device desktop|mobile]
seoctopus rank history -d [-k keywords...] [--days 30]
# SEO auditing
seoctopus audit page
seoctopus audit site [-p maxPages] [-d depth]
seoctopus audit content [-k keyword]
seoctopus audit links [-e checkExternal]
# Performance
seoctopus perf audit [--device mobile|desktop]
seoctopus perf cwv [-s mobile|desktop]
seoctopus perf compare [url3...] [--device mobile|desktop]
# Google Analytics
seoctopus analytics overview -p [--date last28days] [--compare previousPeriod]
seoctopus analytics pages -p [--sort pageviews|engagement|bounceRate|conversions]
seoctopus analytics realtime -p
# Keywords
seoctopus keywords gsc -s [--sort clicks|impressions|ctr|position]
seoctopus keywords suggest [-c country]
seoctopus keywords gaps -s [--min-impressions 100] [--max-position 20]
seoctopus keywords cluster [keyword3...]
# Competitive
seoctopus compete analyze [-u yourUrl] [-n numCompetitors]
seoctopus compete gap [competitorUrl2...]
seoctopus compete share [keyword2...] -d
# Scoring & Reports
seoctopus score [-k keyword] [-p ga4PropertyId]
seoctopus report [-k keyword] [-f json|markdown|html] [-o outputFile]
# Auth & Config
seoctopus auth setup -c
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
| 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
```bash
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](https://www.skool.com/ai-elite-9507/about?ref=67521860944147018da6145e3db6e51c)
---
## Contributing
Found a bug or have an idea? Open an issue.
Built something cool with SEOctopus? Open a PR.
## License
MIT — Go build something.