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.mdskills/openseo/SKILL.md
GitHubOpenSEO — 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
- Run
mktg seo status --json --fields readiness,catalog,project,bindingCorrupt,state. - Interpret readiness:
hosted_oauth_ready: agent MCP client is authenticated interactively.hosted_api_key_ready: headless hosted MCP can useOPENSEO_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 rankunknown.
- Read
.seo/openseo.json. If absent and project-scoped tools are needed, useopenseo-project-setup. - Read
get_project_contextbefore rebuying research. Use its research log to identify still-fresh evidence. - Select only the tools needed from the v0.1.6 tool map.
Authentication
- Root
.mcp.jsonintentionally declares the hosted URL without a bearer header so MCP clients can perform OpenSEO OAuth. - Headless clients may add
Authorization: Bearer ${OPENSEO_API_KEY}orx-api-key: ${OPENSEO_API_KEY}in their private client config. Never write a key value into the repository. OPENSEO_MCP_URLoverrides the endpoint for self-hosting. Hosted default ishttps://app.openseo.so/mcp.mktg catalog info openseoreports headless API-key readiness;mktg seo statusdistinguishes 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, andupdate_project_contextmutate 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: falseas proof OAuth is disconnected — catalog readiness is headless env readiness;mktg seo statusowns 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-seodirect 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.