SEO自动化工具

SUUR TÕLL — Autonomous AI SEO Agent

Named after the giant of Saaremaa, the legendary hero of Estonian mythology who carried impossible loads across the land. This tool does the same for SEO.

SUUR TÕLL is a per-project AI SEO agent you deploy inside any website project. It connects to your real data (Google Search Console, your live site, SERP results), does the analysis, writes content, tracks it on a persistent task board, and comes back 30 days later to check if it worked.

No dashboards. No subscriptions. Just a CLI and an MCP server that lives in your project.

What It Does — 11 Tools, One Conversation

Quick Start (5 Steps)

1. Install

pip install suurtoell
# or from source:
git clone https://github.com/aidoskye/suurtoell
cd suurtoell
pip install -e .

2. Set environment variables

export ANTHROPIC_API_KEY=sk-ant-...
export BRAVE_API_KEY=BSA...
export DATAFORSEO_LOGIN=your@email.com
export DATAFORSEO_PASSWORD=yourpassword

Add these to your shell profile (~/.zshrc or ~/.bashrc) so they persist.

3. Initialize your project

cd /path/to/your/website-project
suurtoell init

This creates config.yaml and .suurtoell/ in your project directory.

4. Authenticate with Google Search Console

suurtoell auth

A browser window opens. Sign in with the Google account that has GSC access. Token is saved locally.

5. Run your first audit

suurtoell audit

Done. Your task board is now populated with real findings.

Per-Project Deployment

SUUR TÕLL is installed once globally and configured per project:

your-website/
  config.yaml          ← project-specific config (site URL, GSC property, brand voice)
  .suurtoell/
    tasks.json         ← persistent task board
    gsc-token.json     ← GSC OAuth token (auto-generated)
    crawl-cache/       ← cached crawl data (24h TTL)
    reports/           ← generated briefs and articles

Each project has its own config, task board, and cache. The suurtoell binary is global.

CLI Reference

suurtoell init                    # Interactive setup wizard
suurtoell auth                    # Authenticate Google Search Console
suurtoell audit                   # Full site audit → task board
suurtoell audit --skip-gsc        # Audit without GSC (crawl only)
suurtoell audit --days 30         # Use 30 days of GSC data
suurtoell crawl                   # Crawl site, update cache
suurtoell crawl --force           # Force re-crawl
suurtoell tasks list              # View task board
suurtoell tasks list --state todo # Filter by state
suurtoell tasks list --priority high
suurtoell tasks done <id>         # Mark task complete
suurtoell tasks export            # Export to seo-tasks.md
suurtoell brief "your keyword"    # Generate content brief
suurtoell write "your keyword"    # Generate full article
suurtoell write "keyword" --match-style  # Match your brand voice
suurtoell reeval                  # Run reevaluation loop
suurtoell report                  # Generate full SEO health report
suurtoell serve                   # Start MCP server

MCP Setup (Claude / OpenClaw Integration)

The real power: use SUUR TÕLL conversationally inside Claude.

Add to your project's .mcp.json:

{
  "mcpServers": {
    "suurtoell": {
      "command": "suurtoell",
      "args": ["serve"]
    }
  }
}

Then in Claude Code:

"Analyze the SERP for 'best project management tools for startups' and generate a content brief" "What are my top impression-wasting pages this month?" "Write an article for 'notion alternatives 2025' matching my brand voice"

Config Reference

Copy config.example.yaml to config.yaml in your project root.

project:
  name: "My Site"
  url: "https://example.com"
  gsc_property: "sc-domain:example.com"   # or "https://example.com/"
  cms: "wordpress"                          # wordpress|webflow|shopify|headless|none
  language: "en"
  country: "US"

brand:
  voice: "professional yet approachable"
  avoid: ["synergy", "leverage"]
  style_sample_urls:
    - "https://example.com/blog/my-best-post"

llm:
  model: "claude-sonnet-4-5"
  max_tokens: 8192

integrations:
  google_search_console:
    credentials_file: "~/.suurtoell/gsc-credentials.json"
    token_file: ".suurtoell/gsc-token.json"
  dataforseo:
    enabled: true
  brave_search:
    enabled: true
    results_count: 10

API Keys Setup

Anthropic (Claude)

1. Go to console.anthropic.com
2. API Keys → Create Key
3. export ANTHROPIC_API_KEY=sk-ant-...

Brave Search (SERP analysis)

1. Go to brave.com/search/api/
2. Sign up → Free tier: 2,000 req/month
3. export BRAVE_API_KEY=BSA...

DataForSEO (keyword volume + competition)

1. Go to dataforseo.com
2. Sign up → get login/password
3. Pay-per-use: ~$0.0005/keyword — very cheap
4. Free sandbox available for testing
5. export DATAFORSEO_LOGIN=your@email.com
6. export DATAFORSEO_PASSWORD=yourpassword

Google Search Console (OAuth2)

1. Go to Google Cloud Console
2. Create project → Enable "Google Search Console API"
3. Credentials → Create OAuth 2.0 Client ID (Desktop app)
4. Download JSON → save to ~/.suurtoell/gsc-credentials.json
5. Run suurtoell auth — browser flow, token auto-saved

Task Board

Every finding from an audit becomes a task. Tasks have types, priorities, and states:

Types: content_gap | declining_page | cannibalization | missing_links | title_optimization | new_article

States: todo → in_progress → done | declined

Priorities: high | medium | low

The reevaluation loop (suurtoell reeval) runs 30 days after task creation and checks:

• Did the page's ranking improve?
• Did the CTR increase?
• Is the issue resolved?

Closes what's fixed. Creates new tasks for what's still declining.

Architecture

See ARCHITECTURE.md for the full technical breakdown.

License

MIT — build on it, deploy it, make money with it.

SUUR TÕLL was the giant of Saaremaa. He carried stones across the sea, protected his people, and did work no one else could. That's the energy.