claude-seo-pi

claude-seo ported to the pi and omp coding agents.

33 SEO skills, 20 specialist agents and 50+ Python tools covering technical SEO, content quality (E-E-A-T), schema markup, GEO/AI search, local SEO, backlinks, rank tracking and drift monitoring.

Install

# pi
pi install npm:claude-seo-pi

# omp
omp plugin install claude-seo-pi

Requirements

Everything else (BeautifulSoup, Playwright/Chromium, Google API clients, matplotlib/WeasyPrint) is installed into the managed virtualenv by /seo setup.

Provision the runtime once. Neither pi install nor omp plugin install runs provisioning steps, so the Python environment is created on demand:

/seo setup      # creates the venv and Chromium (a few hundred MB, one time)
/seo doctor     # read-only check; prints core and Chromium status separately

/seo setup is idempotent, and the environment lives in a per-user data directory (~/.local/share/claude-seo on Linux, ~/Library/Application Support/claude-seo on macOS, %LOCALAPPDATA%\claude-seo on Windows), so it survives package upgrades and is shared between pi and omp.

On pi, install the subagent extension too:

pi install npm:pi-subagents

This is what makes the 20 specialist agents dispatchable. It is deliberately not a dependency of this package: pi does not register a dependency as a package, so a bundled copy would be installed but never loaded, and would risk shadowing your own. Without it every skill still works — audits simply run sequentially instead of delegating in parallel. omp has native agent support and needs nothing extra.

Verify

/seo doctor

Expect "ready": true. On pi, pi list should show claude-seo-pi; on omp, omp plugin list and omp plugin doctor.

Quick start

# first run, once
/seo setup

# audit a site (delegates to specialist agents in parallel)
/seo audit https://example.com

# or a single page
/seo page https://example.com/pricing

A full audit detects the business type (SaaS, local, e-commerce, publisher, agency), spawns the relevant specialists, and returns a scored report with findings bucketed Critical / High / Medium / Low plus a sequenced action plan. Expect it to take a few minutes: it fetches pages, parses HTML, and may run Lighthouse. Narrow commands are much faster — /seo schema <url> or /seo sitemap <url> return in seconds and touch a single concern.

Nothing here requires an API key. Without credentials, Core Web Vitals are lab estimates and indexation is inferred from page signals. Google API credentials add real field data; MCP extensions add competitive and AI-citation data. Both are opt-in.

Commands

Every skill is also directly invocable as /skill:seo-<name>.

Analysis

Integrations

These need credentials or an MCP server — see Optional integrations.

/seo google alone has 20+ subcommands (pagespeed, crux, crux-history, gsc, inspect, sitemaps, index, ga4, ga4-pages, keywords, volume, youtube, nlp, entities, safety, quotas, report, …). Run /seo google setup for the credential walkthrough.

Maintenance

Optional integrations

All optional. Each is off until you configure it; the skill tells you when its prerequisite is missing. Every installer section below is what the upstream install.sh scripts would have configured — those write to ~/.claude.json, which pi and omp do not read, so the equivalent lives here instead.

Google APIs (free, no MCP server)

Four additive tiers. Start at Tier 0 with one API key; add access only when a workflow needs it.

All four are free within Google's normal quota limits; you supply your own Google Cloud project. For Tier 0, go to console.cloud.google.com, enable PageSpeed Insights API and Chrome UX Report API in your project, create an API key restricted to those two, and write it to ~/.config/claude-seo/google-api.json (chmod 600):

{ "api_key": "AIza..." }

For Tier 1+, add a service account: download its JSON key, and add its client_email as a user on the Search Console property (Full, or Owner for the Indexing API) and as a Viewer on the GA4 property. Credentials can also come from the environment (GOOGLE_API_KEY, GOOGLE_APPLICATION_CREDENTIALS, GA4_PROPERTY_ID, GSC_PROPERTY). Check what you unlocked with /seo google setup and /seo google quotas.

The Indexing API only accepts eligible JobPosting pages and BroadcastEvent pages embedded in VideoObject; a notification is not a guarantee of indexing. CrUX returns data only when a URL or origin has enough eligible Chrome traffic.

MCP servers

MCP config is per-runtime. pi reads it through pi-mcp-adapter (pi install npm:pi-mcp-adapter), which accepts the standard .mcp.json envelope:

Add the servers you want under mcpServers:

{
  "mcpServers": {
    "firecrawl-mcp": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp@3.11.0"],
      "env": { "FIRECRAWL_API_KEY": "fc-..." }
    },
    "dataforseo": {
      "command": "npx",
      "args": ["-y", "dataforseo-mcp-server@2.8.10"],
      "env": {
        "DATAFORSEO_USERNAME": "...",
        "DATAFORSEO_PASSWORD": "...",
        "ENABLED_MODULES": "SERP,KEYWORDS_DATA,ONPAGE,DATAFORSEO_LABS,BACKLINKS,DOMAIN_ANALYTICS,BUSINESS_DATA,CONTENT_ANALYSIS,AI_OPTIMIZATION"
      }
    },
    "ahrefs": {
      "command": "npx",
      "args": ["--yes", "--package=@ahrefs/mcp@0.0.11", "mcp"],
      "env": { "AHREFS_API_TOKEN": "..." }
    },
    "nanobanana-mcp": {
      "command": "npx",
      "args": ["-y", "@ycse/nanobanana-mcp@1.1.1"],
      "env": { "GOOGLE_AI_API_KEY": "..." }
    }
  }
}

Restart the session, then verify with /mcp in pi or your omp MCP command. The skill checks for its tools before use and tells you if the server is missing.

Environment variables

These integrations need no MCP server, only credentials:

Three runtime variables are set for you by the extension, documented here only because setting them yourself overrides the default:

Skills

seo (orchestrator) · seo-agentic · seo-ahrefs · seo-audit · seo-backlinks · seo-bing · seo-cluster · seo-competitor-pages · seo-content · seo-content-brief · seo-dataforseo · seo-drift · seo-ecommerce · seo-firecrawl · seo-flow · seo-geo · seo-google · seo-hreflang · seo-image-gen · seo-images · seo-local · seo-maps · seo-matomo · seo-page · seo-plan · seo-profound · seo-programmatic · seo-schema · seo-seranking · seo-sitemap · seo-sxo · seo-technical · seo-unlighthouse

Each skill's own references/ directory holds the detail for that domain.

Troubleshooting

Uninstall

# pi
pi remove npm:claude-seo-pi

# omp
omp plugin uninstall claude-seo-pi

The managed Python environment in ~/.local/share/claude-seo is not removed — delete it manually to reclaim the disk. Credentials under ~/.config/claude-seo/ are likewise left alone.

Contributing

This is a port, not a fork: the upstream plugin is vendored at a pinned tag and transformed at build time, and the generated trees (skills/, agents/, scripts/, extensions/) are rebuilt on every sync — edit them upstream or in tools/sync.mjs, never in place.

CONTRIBUTING.md covers the build, the test suites, the rules the build enforces, and the upstream findings this port deliberately does not patch.

Credits

Ported from claude-seo v2.4.0 by AgriciDaniel, MIT licensed. Upstream contributors include Lutfiya Miller (seo-cluster), Florian Schmitz (seo-sxo), Dan Colta (seo-drift) and Chris Muller (seo-hreflang).