openseo

Uses OpenSEO as the measured SEO data plane for keyword volume and difficulty, SERPs, ranked keywords, backlinks, local SEO, rank tracking, Search Console, GA4, and site audits. Use for measured SEO m

SKILL.md

GitHub

OpenSEO — Measured SEO Data Plane

OpenSEO supplies evidence; mktg skills supply methodology. Communicate only through OpenSEO's MCP-over-HTTP endpoint. There is no general OpenSEO REST research API, and mktg never calls DataForSEO directly.

On Activation

  1. Run mktg seo status --json --fields readiness,catalog,project,bindingCorrupt,state.
  2. Interpret readiness:
    • hosted_oauth_ready: agent MCP client is authenticated interactively.
    • hosted_api_key_ready: headless hosted MCP can use OPENSEO_API_KEY.
    • selfhost_ready: bound/connected non-hosted MCP endpoint; local Docker HTTP is allowed only on loopback.
    • not_configured: continue through Exa/crawl/manual evidence and label KD, volume, CPC, authority, and rank unknown.
  3. Read .seo/openseo.json. If absent and project-scoped tools are needed, use openseo-project-setup.
  4. Read get_project_context before rebuying research. Use its research log to identify still-fresh evidence.
  5. Select only the tools needed from the v0.1.6 tool map.

Authentication

  • Root .mcp.json intentionally declares the hosted URL without a bearer header so MCP clients can perform OpenSEO OAuth.
  • Headless clients may add Authorization: Bearer ${OPENSEO_API_KEY} or x-api-key: ${OPENSEO_API_KEY} in their private client config. Never write a key value into the repository.
  • OPENSEO_MCP_URL overrides the endpoint for self-hosting. Hosted default is https://app.openseo.so/mcp.
  • mktg catalog info openseo reports headless API-key readiness; mktg seo status distinguishes OAuth, API key, and self-host modes.

Route Evidence, Do Not Duplicate Playbooks

Need OpenSEO evidence mktg owner
Keyword demand/opportunity keyword research, metrics, ranked terms, GSC openseo-keyword-research
Page mapping/cannibalization query+page GSC, SERPs, ranked URLs openseo-keyword-clustering
Market/competitor SERP competitors, domain/ranked terms, backlink profiles competitive OpenSEO skills
Technical/indexing site audit, URL inspection, GSC seo-audit
Local visibility business, local SERP, reviews, categories, rank grid seo-audit with local mode/brief
Organic outcomes GA4 landing/page/event/acquisition/opportunity tools seo-audit, seo-content, seo-machine
AEO hypotheses SERP, index, audit, backlink, GSC, GA4 evidence only ai-seo owns direct answer-engine observations

Cost and Mutation Policy

Before a paid batch, state the exact tool(s), item counts, requested limits, and cost shape. OpenSEO's server requests confirmation above its large-credit threshold, but mktg still asks whenever the planned spend is material or recurring.

Separate spend from mutation:

  • whoami, project/context reads, saved-keyword reads, GSC, and GA4 are free reads.
  • save_keywords, create_project, tags, and update_project_context mutate shared account state but do not themselves consume DataForSEO credits; confirm broad/destructive changes.
  • research, SERP, backlinks, local SEO, site audit, and rank runs may consume credits.
  • scheduled rank tracking requires estimate_rank_tracker_cost, explicit approval, and the approved credit ceiling passed to the write/run call.

State Contract

Evidence Local contract
project/domain/MCP URL .seo/openseo.json
keyword transfer .seo/keywords-sync.json → mktg seo sync-keywords --confirm
rank observations .seo/rank-snapshots/<date>.json
backlinks .seo/backlinks/<date>.json with target scope, pagination, and provider limits
GSC / GA4 exports .seo/gsc/, .seo/ga4/ when a file snapshot is needed
site audits .seo/audits/<audit-id>.json plus summary

OpenSEO remains the measurement backend; brand/ and the active playbook tracker remain mktg's decision memory.

Anti-Patterns

  • Inventing REST endpoints — upstream automation is MCP-over-HTTP; guessed REST paths fail and misstate the security boundary.
  • Treating configured: false as proof OAuth is disconnected — catalog readiness is headless env readiness; mktg seo status owns the richer truth.
  • Calling DataForSEO directly — this bypasses OpenSEO's project, usage, and cost controls.
  • Calling free account mutations “paid research” — spend and shared-state risk need different approvals.
  • Saving only backlink totals — scope (exact, subfolder, domain, subdomains), pagination, and provider limitations determine what totals mean.
  • Claiming OpenSEO MCP measures AI answers — v0.1.6 has no AI Visibility MCP tools. Use ai-seo direct observations and OpenSEO supporting evidence.

Progressive Enhancement

Level Behavior
L0 Qualitative web/manual evidence; metrics unknown.
L1 Hosted OAuth or API key exposes measured MCP tools.
L2 Bound project/context avoids duplicate spend and enables GSC/GA4.
L3 Synced snapshots feed mktg playbooks and long-arc trackers.

After writing artifacts, log completion with mktg run openseo --complete --writes <paths> --result success --json.


OpenSEO integration targets every-app/open-seo v0.1.6 over an MIT-safe HTTP/MCP boundary.