# OurSEO Agent (CLI + MCP)

The OurSEO Agent (`~/Project/our-seo-agent`) covers two distinct paths for this skill:

1. **CLI** — `our keywords *` (Claude Code, via Bash). DataForSEO under the hood. Cheapest per call, batch-friendly, Korean-aware.
2. **MCP** — `mcp__ourseo__*` (Claude Desktop). Lighter surface: crawl, audit, Knowledge Graph entity expansion.

Pick the path that matches your current Claude environment.

## CLI commands (Claude Code, primary for Korean market)

```bash
# Volume + difficulty + intent
our keywords volume "<keyword>" --location 2410 --language ko
our keywords difficulty "<kw1>" "<kw2>" --location 2410
our keywords intent "<kw1>" "<kw2>" "<kw3>"

# Expansion
our keywords ideas "<seed>" --location 2410 --limit 50
our keywords for-site <competitor.com> --location 2410 --limit 100

# Naver (Korean engines)
our research naver keywords volume "<keyword>"
our research naver keywords ideas "<keyword>" --limit 30

# Cross-engine compare (where supported)
our research keywords compare "<keyword>" --engines naver
```

| Location code | Market |
|---|---|
| `2410` | Korea |
| `2840` | United States |
| `2392` | Japan |

| Language code | Language |
|---|---|
| `ko` | Korean |
| `en` | English |
| `ja` | Japanese |

Cache (avoid duplicate calls): `our research cache list --engine <name>` / `our research cache clear --older-than 30d`.

## MCP tools (Claude Desktop)

| Tool | Purpose for keyword work |
|---|---|
| `mcp__ourseo__search_knowledge_graph` | Resolve a brand / entity to Knowledge Graph IDs — useful as a *seeding* step for keyword expansion around the entity. |
| `mcp__ourseo__crawl_website` | Crawl the target site and pull on-page keyword inventory (title/h1/meta) — ground truth for what the site already targets. |
| `mcp__ourseo__audit_page` | Single-page SEO audit; not a keyword tool per se, but useful for validating that high-value keywords are actually present on the page. |
| `mcp__ourseo__check_serp` | Check SERP position for a keyword/domain pair — bridge to position tracking. |
| `mcp__ourseo__find_similar_pages` | Semantic similarity over a prior crawl — supports topic clustering. |

The OurSEO MCP does **not** expose DataForSEO keyword volume directly. For volume + KD + ideas in Claude Desktop, use Semrush MCP (`mcp__semrush__*`) or DataForSEO MCP (`mcp__dfs-mcp__*`).

## Configuration

The CLI reads from `~/Project/our-seo-agent/config/config.yaml` and these env vars:

| Variable | Purpose |
|---|---|
| `DATAFORSEO_USERNAME` / `DATAFORSEO_PASSWORD` | DataForSEO auth |
| `NAVER_CLIENT_ID` / `NAVER_CLIENT_SECRET` | Naver Open API + Search Ad |
| `GOOGLE_KG_API_KEY` | Knowledge Graph Search API |

See the project `CLAUDE.md` for full env-var reference. Credentials live in 1Password — fetch with `op://Development/<item>/credential`.

## When to choose OurSEO over Semrush / Ahrefs

- Korean-market batch work (Naver + Google together).
- Crawl-derived keyword inventory (what the site itself targets, not estimates).
- Knowledge Graph entity seeding.
- Cost-sensitive bulk volume lookups.
- Cross-engine comparison (Naver + DataForSEO via `our research keywords compare`).