AI SEO Agent

AI-powered SEO analysis system with parallel agents and LangGraph orchestration

Open-source CLI tool that fully automatically analyzes websites for SEO, finds competitors, evaluates keywords, and generates a detailed HTML report — all locally and for free with Ollama.

Highlights

5 specialized AI agents working in parallel on the analysis
LangGraph Orchestrator controls the workflow with fan-out/fan-in pattern
Animated CLI with ASCII art banner, gradient colors, spinners, and score bars
Completely free — Ollama (local) + DuckDuckGo (no API key required)
12 SEO check categories with 60+ individual checks
HTML dark-theme report with score circle, severity badges, and AI recommendations
Structured data throughout with Zod schemas + TypeScript types
Graceful degradation — works without LLM (rule-based)

Architecture

                         ┌─────────┐
                         │  START  │
                         └────┬────┘
                              │
                       ┌──────▼──────┐
                       │   CRAWLER   │   Fetch + parse website
                       │   Agent     │   (Cheerio HTML Parser)
                       └──────┬──────┘
                              │
              ┌───────────────┼───────────────┐
              │               │               │
       ┌──────▼──────┐ ┌─────▼──────┐ ┌──────▼──────┐
       │  ANALYZER   │ │ COMPETITOR │ │  KEYWORD    │   Parallel
       │  Agent      │ │ Agent      │ │  Agent      │   Execution
       │  (SEO Checks│ │ (DuckDuck- │ │  (Density,  │
       │  + LLM)     │ │  Go Search)│ │  Rankings)  │
       └──────┬──────┘ └─────┬──────┘ └──────┬──────┘
              │               │               │
              └───────────────┼───────────────┘
                              │
                       ┌──────▼──────┐
                       │  REPORTER   │   Generate HTML report
                       │  Agent      │   (Handlebars Template)
                       └──────┬──────┘
                              │
                         ┌────▼────┐
                         │   END   │
                         └─────────┘

Project Structure

AISeoAgent/
├── package.json                 # Dependencies + Scripts
├── tsconfig.json                # TypeScript ESM Config
├── .env                         # LLM + HTTP Configuration
│
├── src/
│   ├── index.ts                 # CLI Entry Point (Commander)
│   ├── config.ts                # Configuration + LLM Factory
│   ├── types.ts                 # Zod Schemas + TypeScript Types
│   │
│   ├── cli/                     # Animated CLI
│   │   ├── banner.ts            #   ASCII Art + Gradient
│   │   ├── ui.ts                #   Spinners, Tables, Score Bars
│   │   └── app.ts               #   CLI Workflow + Control
│   │
│   ├── agents/                  # LangGraph Agent Nodes
│   │   ├── crawler.ts           #   Website Crawler
│   │   ├── analyzer.ts          #   SEO Analysis + LLM
│   │   ├── competitor.ts        #   Competitor Search
│   │   ├── keyword.ts           #   Keyword Analysis
│   │   └── reporter.ts          #   Report Generator
│   │
│   ├── graph/                   # LangGraph Orchestrator
│   │   ├── state.ts             #   State Definition (Annotation)
│   │   └── workflow.ts          #   Workflow (Parallel Edges)
│   │
│   ├── tools/                   # Analysis Tools
│   │   ├── scraper.ts           #   Cheerio Web Scraper
│   │   ├── seoChecks.ts         #   7 SEO Check Functions
│   │   └── search.ts            #   DuckDuckGo Search
│   │
│   └── reports/                 # Report Generation
│       ├── generator.ts         #   Handlebars Renderer
│       └── template.ts          #   Dark-Theme HTML Template
│
├── mcp/                         # MCP Server (Model Context Protocol)
│   ├── package.json             #   MCP Dependencies
│   ├── tsconfig.json            #   TypeScript Config
│   └── src/
│       ├── index.ts             #   MCP Server Entry Point
│       ├── types.ts             #   Shared Zod Schemas
│       ├── scraper.ts           #   Web Scraper (Cheerio + Puppeteer)
│       ├── seoChecks.ts         #   SEO Check Functions
│       └── search.ts            #   DuckDuckGo Search
│
└── reports/                     # Generated HTML Reports

Installation

Prerequisites

Node.js >= 18.0
npm or pnpm
Ollama (optional, for AI recommendations)

Setup

# Clone the repository
git clone https://github.com/zurd46/ai-seo-agent.git
cd ai-seo-agent

# Install dependencies
npm install

# Configure environment variables
cp .env.example .env

Set up Ollama (optional, free)

# Install Ollama (macOS)
brew install ollama

# Start Ollama
ollama serve

# Download a model
ollama pull llama3.1

Without Ollama, the system works fully with rule-based SEO checks. The LLM only adds AI-generated recommendations and summaries.

Usage

Full SEO Analysis

npx tsx src/index.ts analyze https://example.com

Runs the complete workflow:

Crawling — Load website, parse HTML, extract meta tags/links/images
Parallel Analysis — SEO checks, competitor search, keyword analysis simultaneously
Report — Generate HTML report and open in browser

Quick Crawl

npx tsx src/index.ts crawl https://example.com

Only crawl the website and display basic information (without analysis).

Help

npx tsx src/index.ts --help

SEO Checks

The system performs 60+ individual checks across 12 categories:

Category	Checks
Title Tag	Present, length (30-60 chars), domain-only detection, separator start, duplicate words, ALL CAPS, CTR boosters (numbers/power words)
Meta Description	Present, length (120-160 chars), unique vs title, call-to-action presence, numbers/stats for CTR
Headings	H1 count (exactly 1), H1 length, H1 vs title, H2/H3 structure, hierarchy continuity, duplicates, short headings, keyword stuffing, heading-to-content ratio
Images	Alt texts (missing, generic, too long), width/height attributes (CLS), next-gen formats (WebP/AVIF), descriptive filenames, lazy loading for below-fold
Links	Internal/external count, empty anchors, generic anchors ("click here"), nofollow on internal, excessive duplicates, total link count
Technical	HTTP status, HTTPS, redirects, load time, robots.txt, noindex/nofollow, sitemap, viewport, canonical, lang attribute, page size, DOCTYPE, favicon, mixed content, deprecated HTML tags
Content	Word count, text-to-HTML ratio, Schema.org/JSON-LD, readability (sentence length), long sentences, paragraph structure, list usage
Social Media	og:title, og:description, og:image, og:type, Twitter Card, completeness check
URL	Parameters, length, uppercase, underscores, special chars, directory depth, file extensions
Accessibility	ARIA landmarks, semantic HTML, skip navigation, form labels, positive tabindex, iframe titles, button labels, image alt (a11y)
Performance	Render-blocking scripts, inline CSS/JS size, external resource count, resource hints (preconnect/preload), HTML payload size, mixed content
International	Hreflang tags, x-default, self-referencing hreflang, valid language codes, lang attribute consistency

Severity Levels

CRITICAL — Severe issue, fix immediately
WARNING — Should be fixed, medium priority
INFO — Improvement suggestion, low priority
GOOD — No action needed, positive signal

Agents in Detail

Crawler Agent

Fetches the target URL and extracts all SEO-relevant data:

HTTP status, load time, content type, HTTPS
Meta tags (title, description, robots, canonical, viewport)
Open Graph + Twitter Card tags
Heading structure (H1-H6) in document order
Internal and external links with anchor texts
Images with alt text, dimensions, lazy loading, format analysis
Schema.org / JSON-LD structured data
Robots.txt and sitemap.xml check
Favicon and DOCTYPE detection
Hreflang tags (international SEO)
Accessibility data (ARIA landmarks, form labels, skip nav, iframes, buttons)
Performance data (inline CSS/JS, render-blocking scripts, resource hints, mixed content)
Content structure (paragraphs, sentence length, lists, tables, deprecated tags)

Analyzer Agent

Runs all 7 SEO check categories and calculates scores (0-100). Optionally, an LLM generates prioritized action recommendations based on the issues found.

Competitor Agent

Searches via DuckDuckGo for websites ranking for the same keywords. Identifies keyword overlap and analyzes the competitive landscape. LLM-driven competitive analysis with strengths, weaknesses, and opportunities.

Keyword Agent

Extracts the most frequent keywords from the page content. Evaluates:

Keyword density (frequency in text)
Prominence score (presence in title, H1, description, URL)
DuckDuckGo rankings (approximate position)
Content gaps (missing keywords)

Reporter Agent

Generates a comprehensive HTML report in dark-theme design with:

Score circle visualization
Category score bars
Issue table with severity badges
Competitor overview
Keyword analysis table
AI-generated recommendations
Structured data overview

Configuration

`.env` File

# LLM Provider: "ollama" (free), "openai" or "anthropic"
LLM_PROVIDER=ollama

# Ollama (default - free, local)
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3.1

# Optional: OpenAI
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o

# Optional: Anthropic
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_MODEL=claude-sonnet-4-5-20250929

# HTTP
REQUEST_TIMEOUT=30
MAX_CONCURRENT_REQUESTS=5

Switching LLM Provider

The system supports 3 LLM providers:

Provider	Cost	Setup
Ollama	Free	`ollama serve` + `ollama pull llama3.1`
OpenAI	Paid	Set API key in `.env`
Anthropic	Paid	Set API key in `.env`

HTML Report

The generated report includes:

Executive Summary — AI-generated summary of key findings
Page Information — Status, load time, HTTPS, meta tags, links, images
SEO Scores — Score bars for each of the 7 categories
Issues Found — Sorted by severity with actual/expected comparison and recommendations
AI Recommendations — LLM-generated prioritized action recommendations
Competitor Analysis — Top competitors with keyword overlap
Keyword Analysis — Primary/secondary keywords with prominence score
Structured Data — Found Schema.org/JSON-LD entries

Reports are saved under reports/ and automatically opened in the browser.

Tech Stack

Technology	Usage
TypeScript	Type-safe codebase, ESM modules
LangGraph	Workflow orchestration with parallel agent execution
LangChain	LLM abstraction (Ollama, OpenAI, Anthropic)
Zod	Schema validation + TypeScript type inference
Cheerio	Fast HTML parsing (server-side)
Commander	CLI command parsing
Chalk	Terminal colors
Ora	Terminal spinners/animations
Boxen	Terminal boxes
Gradient-String	Gradient text in terminal
Figlet	ASCII art text
CLI-Table3	Formatted terminal tables
Handlebars	HTML template engine
DuckDuckGo	Free web search (no API key)

CLI Preview

███████╗███████╗ ██████╗      █████╗  ██████╗ ███████╗███╗   ██╗████████╗
██╔════╝██╔════╝██╔═══██╗    ██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝
███████╗█████╗  ██║   ██║    ███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║
╚════██║██╔══╝  ██║   ██║    ██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║
███████║███████╗╚██████╔╝    ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║
╚══════╝╚══════╝ ╚═════╝     ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝

  AI-Powered SEO Analysis System  |  v1.0.0
  LangGraph Orchestrator + Parallel Agent Execution

  ▸ Phase 1: Website Crawling ·····························
  ✔ Website successfully crawled

  ▸ Phase 2: Parallel Agent Analysis ······················
  ✔ SEO analysis completed (Score: 64/100)
  ✔ 10 competitors found
  ✔ 13 keywords analyzed

  ▸ Phase 3: Results ······································
  ┌────────────────────┬──────────┬──────────────────────────────────┐
  │ Category           │ Score    │ Bar                              │
  ├────────────────────┼──────────┼──────────────────────────────────┤
  │ Title Tag          │ 70/100   │ █████████████████████░░░░░░░░░   │
  │ Meta Description   │ 0/100    │ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  │
  │ Headings           │ 85/100   │ ██████████████████████████░░░░   │
  │ Images             │ 100/100  │ ██████████████████████████████   │
  │ Technical          │ 75/100   │ ███████████████████████░░░░░░░   │
  └────────────────────┴──────────┴──────────────────────────────────┘

  ▸ Phase 4: Report Generation ····························
  ✔ HTML report generated

  ╔═ SEO Analysis Complete ═════════════════════════════════╗
  ║  Report saved: reports/seo_report_example.html          ║
  ║  Duration: 5.4s                                         ║
  ╚═════════════════════════════════════════════════════════╝

Development

# Compile TypeScript
npm run build

# Development mode (tsx)
npm run dev

# Run directly
npx tsx src/index.ts analyze https://example.com

MCP Server (Model Context Protocol)

The project includes an MCP server that exposes the full SEO analysis pipeline as tools for AI assistants (Claude, etc.). The server takes a URL as input and returns structured JSON results.

MCP Tools

Tool	Description
`crawl_url`	Crawl a website and extract all SEO-relevant data (meta tags, headings, links, images, structured data, load time, robots.txt, sitemap)
`analyze_seo`	Run 30+ SEO checks across 9 categories and return scores (0-100) with detailed issues, severity levels, and recommendations
`find_competitors`	Find competitor websites via DuckDuckGo, identify keyword overlap, and optionally crawl top competitors for detailed SEO comparison
`analyze_keywords`	Extract keywords, calculate density and prominence scores, check approximate DuckDuckGo rankings
`full_seo_report`	Run the complete pipeline (crawl + SEO analysis + competitors + keywords) and return a comprehensive structured report

MCP Setup

# Install MCP server dependencies
cd mcp
npm install

# Build
npm run build

# Run (stdio transport)
npm start

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "ai-seo-agent": {
      "command": "node",
      "args": ["/path/to/AISeoAgent/mcp/dist/index.js"]
    }
  }
}

Example Usage (via AI Assistant)

Once configured, you can ask your AI assistant:

"Analyze the SEO of https://example.com"
"Find competitors for https://mysite.com"
"What keywords does https://example.com rank for?"
"Give me a full SEO report for https://example.com"

The MCP server returns structured JSON data that the AI assistant can interpret and present in a readable format.

Keywords

seo seo-analysis seo-tool seo-audit seo-checker website-analysis ai-agent ai-seo langgraph langchain ollama typescript nodejs cli-tool web-scraping keyword-analysis competitor-analysis seo-report html-report open-source free-seo-tool duckduckgo structured-data schema-org meta-tags on-page-seo technical-seo mcp model-context-protocol

seo seo-analysis seo-tool seo-audit seo-checker website-analysis ai-agent ai-seo langgraph langchain ollama typescript nodejs cli-tool web-scraping keyword-analysis competitor-analysis seo-report html-report open-source free-seo-tool duckduckgo structured-data schema-org meta-tags on-page-seo technical-seo

Roadmap

License

MIT License — see LICENSE for details.

_{Built with LangGraph + TypeScript + Ollama}

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
mcp		mcp
src		src
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

AI SEO Agent

Highlights

Architecture

Project Structure

Installation

Prerequisites

Setup

Set up Ollama (optional, free)

Usage

Full SEO Analysis

Quick Crawl

Help

SEO Checks

Severity Levels

Agents in Detail

Crawler Agent

Analyzer Agent

Competitor Agent

Keyword Agent

Reporter Agent

Configuration

.env File

Switching LLM Provider

HTML Report

Tech Stack

CLI Preview

Development

MCP Server (Model Context Protocol)

MCP Tools

MCP Setup

Claude Desktop Configuration

Example Usage (via AI Assistant)

Keywords

Roadmap

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`.env` File

Packages