KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #cli #claude-code #codex #developer-tools #open-source #agent-skills #ai #dsh-plugin #llm #windows

seoctopus

★ 10 Open GitHub ↗

8-armed SEO intelligence - MCP server + CLI with 23 tools for rank tracking, Google Analytics, site auditing, keyword research, competitive analysis, and performance monitoring

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# SEOctopus

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

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

[![MCP Server](https://img.shields.io/badge/MCP-Server-0066FF?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48Y2lyY2xlIGN4PSIxMiIgY3k9IjEyIiByPSIxMCIgZmlsbD0id2hpdGUiLz48L3N2Zz4=)](https://modelcontextprotocol.io)
[![Node](https://img.shields.io/badge/node-%3E%3D20-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![License](https://img.shields.io/badge/license-MIT-yellow?style=for-the-badge)](https://raw.githubusercontent.com/itsjwill/seoctopus/main/LICENSE)
[![Tools](https://img.shields.io/badge/tools-23-purple?style=for-the-badge)]()
[![GA4](https://img.shields.io/badge/Google_Analytics-GA4-E37400?style=for-the-badge&logo=google-analytics&logoColor=white)]()
[![Search Console](https://img.shields.io/badge/Search_Console-API-458CF5?style=for-the-badge&logo=google&logoColor=white)]()

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

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

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

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`

</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.

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

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

```bash
# 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

```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.

seoctopus

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README