Uses OpenSEO as the measured SEO data plane for keyword

OpenSEO — Measured SEO Data Plane

by MoizIbnYousaf · MIT license · ★ 31 on GitHub

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 metrics, indexing evidence, organic…

---
name: openseo
description: >-
  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 metrics, indexing evidence,
  organic analytics, local rankings, backlink profiles, or rank trackers.
  Prefer OpenSEO over guessed metrics when connected; otherwise continue with
  qualitative web research and mark numeric metrics unknown.
category: seo
tier: nice-to-have
layer: strategy
reads:
  - brand/keyword-plan.md
writes:
  - brand/keyword-plan.md
  - brand/learnings.md
env_vars:

Overview

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.

Manual install (npx, ZIP)

Claude Codenpx skills add MoizIbnYousaf/marketing-cli --skill openseo -g -a claude-code

Claude Code (degit)npx degit MoizIbnYousaf/marketing-cli/skills/openseo#main ~/.claude/skills/openseo

Claude.ai / desktopZip the folder and upload it under Settings → Capabilities → Skills.

Codex, Cursor, other agentsPoint them at SKILL.md. The other files are plain text.

Connects with Agent Alley MCP · agentalley.io/mcp

Files included

SKILL.md6.1 KB

Read SKILL.md here

MoizIbnYousaf/main1 file shown

SKILL.md6.1 KB

Browse every file on GitHub↗

SKILL.md

Show the full text118 lines

openseo/SKILL.md118 lines · 6.1 KB

PreviewCode

Outline

RawView on GitHub

OpenSEO — Measured SEO Data Plane

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 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.
Read .seo/openseo.json. If absent and project-scoped tools are needed, use openseo-project-setup.
Read get_project_context before 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.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.

1	---
2	name: openseo
3	description: >-
4	Uses OpenSEO as the measured SEO data plane for keyword volume and difficulty,
5	SERPs, ranked keywords, backlinks, local SEO, rank tracking, Search Console,
6	GA4, and site audits. Use for measured SEO metrics, indexing evidence,
7	organic analytics, local rankings, backlink profiles, or rank trackers.
8	Prefer OpenSEO over guessed metrics when connected; otherwise continue with
9	qualitative web research and mark numeric metrics unknown.
10	category: seo
11	tier: nice-to-have
12	layer: strategy
13	reads:
14	- brand/keyword-plan.md
15	writes:
16	- brand/keyword-plan.md
17	- brand/learnings.md
18	env_vars:
19	- OPENSEO_API_KEY
20	- OPENSEO_MCP_URL
21	triggers:
22	- keyword difficulty
23	- search volume
24	- serp results
25	- ranked keywords
26	- backlinks
27	- rank tracker
28	- gsc performance
29	allowed-tools:
30	- Bash(mktg catalog *)
31	- Bash(mktg doctor *)
32	- Bash(mktg seo *)
33	- Bash(mktg run *)
34	---
35
36	# OpenSEO — Measured SEO Data Plane
37
38	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.
39
40	## On Activation
41
42	1. Run `mktg seo status --json --fields readiness,catalog,project,bindingCorrupt,state`.
43	2. Interpret readiness:
44	- `hosted_oauth_ready`: agent MCP client is authenticated interactively.
45	- `hosted_api_key_ready`: headless hosted MCP can use `OPENSEO_API_KEY`.
46	- `selfhost_ready`: bound/connected non-hosted MCP endpoint; local Docker HTTP is allowed only on loopback.
47	- `not_configured`: continue through Exa/crawl/manual evidence and label KD, volume, CPC, authority, and rank `unknown`.
48	3. Read `.seo/openseo.json`. If absent and project-scoped tools are needed, use `openseo-project-setup`.
49	4. Read `get_project_context` before rebuying research. Use its research log to identify still-fresh evidence.
50	5. Select only the tools needed from the [v0.1.6 tool map](references/tools-v0.1.6.md).
51
52	## Authentication
53
54	- Root `.mcp.json` intentionally declares the hosted URL without a bearer header so MCP clients can perform OpenSEO OAuth.
55	- 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.
56	- `OPENSEO_MCP_URL` overrides the endpoint for self-hosting. Hosted default is `https://app.openseo.so/mcp`.
57	- `mktg catalog info openseo` reports headless API-key readiness; `mktg seo status` distinguishes OAuth, API key, and self-host modes.
58
59	## Route Evidence, Do Not Duplicate Playbooks
60
61	\| Need \| OpenSEO evidence \| mktg owner \|
62	\|---\|---\|---\|
63	\| Keyword demand/opportunity \| keyword research, metrics, ranked terms, GSC \| `openseo-keyword-research` \|
64	\| Page mapping/cannibalization \| query+page GSC, SERPs, ranked URLs \| `openseo-keyword-clustering` \|
65	\| Market/competitor \| SERP competitors, domain/ranked terms, backlink profiles \| competitive OpenSEO skills \|
66	\| Technical/indexing \| site audit, URL inspection, GSC \| `seo-audit` \|
67	\| Local visibility \| business, local SERP, reviews, categories, rank grid \| `seo-audit` with local mode/brief \|
68	\| Organic outcomes \| GA4 landing/page/event/acquisition/opportunity tools \| `seo-audit`, `seo-content`, `seo-machine` \|
69	\| AEO hypotheses \| SERP, index, audit, backlink, GSC, GA4 evidence only \| `ai-seo` owns direct answer-engine observations \|
70
71	## Cost and Mutation Policy
72
73	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.
74
75	Separate spend from mutation:
76
77	- `whoami`, project/context reads, saved-keyword reads, GSC, and GA4 are free reads.
78	- `save_keywords`, `create_project`, tags, and `update_project_context` mutate shared account state but do not themselves consume DataForSEO credits; confirm broad/destructive changes.
79	- research, SERP, backlinks, local SEO, site audit, and rank runs may consume credits.
80	- scheduled rank tracking requires `estimate_rank_tracker_cost`, explicit approval, and the approved credit ceiling passed to the write/run call.
81
82	## State Contract
83
84	\| Evidence \| Local contract \|
85	\|---\|---\|
86	\| project/domain/MCP URL \| `.seo/openseo.json` \|
87	\| keyword transfer \| `.seo/keywords-sync.json` → `mktg seo sync-keywords --confirm` \|
88	\| rank observations \| `.seo/rank-snapshots/<date>.json` \|
89	\| backlinks \| `.seo/backlinks/<date>.json` with target scope, pagination, and provider limits \|
90	\| GSC / GA4 exports \| `.seo/gsc/`, `.seo/ga4/` when a file snapshot is needed \|
91	\| site audits \| `.seo/audits/<audit-id>.json` plus summary \|
92
93	OpenSEO remains the measurement backend; `brand/` and the active playbook tracker remain mktg's decision memory.
94
95	## Anti-Patterns
96
97	- Inventing REST endpoints — upstream automation is MCP-over-HTTP; guessed REST paths fail and misstate the security boundary.
98	- Treating `configured: false` as proof OAuth is disconnected — catalog readiness is headless env readiness; `mktg seo status` owns the richer truth.
99	- Calling DataForSEO directly — this bypasses OpenSEO's project, usage, and cost controls.
100	- Calling free account mutations “paid research” — spend and shared-state risk need different approvals.
101	- Saving only backlink totals — scope (`exact`, `subfolder`, `domain`, `subdomains`), pagination, and provider limitations determine what totals mean.
102	- Claiming OpenSEO MCP measures AI answers — v0.1.6 has no AI Visibility MCP tools. Use `ai-seo` direct observations and OpenSEO supporting evidence.
103
104	## Progressive Enhancement
105
106	\| Level \| Behavior \|
107	\|---\|---\|
108	\| L0 \| Qualitative web/manual evidence; metrics `unknown`. \|
109	\| L1 \| Hosted OAuth or API key exposes measured MCP tools. \|
110	\| L2 \| Bound project/context avoids duplicate spend and enables GSC/GA4. \|
111	\| L3 \| Synced snapshots feed mktg playbooks and long-arc trackers. \|
112
113	After writing artifacts, log completion with `mktg run openseo --complete --writes <paths> --result success --json`.
114
115	---
116
117	OpenSEO integration targets [every-app/open-seo](https://github.com/every-app/open-seo) v0.1.6 over an MIT-safe HTTP/MCP boundary.
118