{
  "markdown": "# Claude Code — SEO Agency & Freelancer Starter\n\n> A batteries-included [Claude Code](https://claude.com/claude-code) blueprint for SEO freelancers and agencies. Wire up the **Visibly AI MCP**, get ready-made slash commands for the full client workflow — Status-Quo → Potential Analysis → Offer → CI-compliant PDF — and a smart hook that nudges Claude toward real SEO data instead of guessing.\n>\n> Built and battle-tested by **[Antonio Blago](https://antonioblago.de)** — SEO Freelancer & creator of the **Neuro-SEO System®**.\n\n<p align=\"center\">\n  <a href=\"#-quickstart\">Quickstart</a> •\n  <a href=\"#-whats-inside\">What's inside</a> •\n  <a href=\"#-the-workflows\">Workflows</a> •\n  <a href=\"#-the-ctr-model\">CTR Model</a> •\n  <a href=\"#-customise-it\">Customise</a> •\n  <a href=\"https://visibly-ai.com\">Get a free key</a> •\n  <a href=\"https://calendly.com/antonio-blago/vibe-coding-consultation?back=1&month=2026-06\">Book a call</a>\n</p>\n\n---\n\n## Why this exists\n\nSEO consulting is the same five jobs over and over: pull the real ranking data, map it against the client's keyword set, quantify the opportunity, turn that into an offer, and ship a presentable PDF. Claude Code can do all of it — *if* you give it the data sources, the methodology, and the guardrails.\n\nThis repo packages exactly that — and it **runs without any API key**. Install it and the bundled `.mcp.json` connects to the [Visibly AI](https://visibly-ai.com) MCP keyless, giving you the free knowledge tools (keyword classification, SEO checklists, Google guidelines, URL-structure analysis) plus the full local methodology; bring your own Search Console export and the entire Status-Quo → Potential → Offer → PDF chain runs offline. Add a Visibly AI key when you want the data engine on tap — live GSC/GA at **0 credits**, keywords, backlinks, competitors and on-page audits through one MCP. Free by default, pro when you need it.\n\n## ✨ What's inside\n\n| Piece | What it does |\n|---|---|\n| **`.mcp.json`** | Pre-wired [Visibly AI MCP](https://visibly-ai.com) connection — **keyless by default** (free knowledge tools); add a key to unlock live GSC, keywords, backlinks, competitors, on-page audits, crawling. |\n| **`/visibly-seo-status-quo`** | Maps a client's live organic visibility: GSC × target keywords, classification, quick wins. |\n| **`/visibly-seo-potential`** | Potential analysis: empirical CTR model → realistic 12-month targets → traffic, lead & ROI math. |\n| **`/visibly-seo-offer`** | Drafts a tailored, phased SEO consulting offer from your analysis + client context. |\n| **`/visibly-seo-pdf-build`** | Turns any analysis script into a clean, brand-compliant PDF. |\n| **SEO hook** | A `UserPromptSubmit` hook that detects SEO intent and steers Claude to Visibly AI MCP tools instead of generic scraping. |\n| **`CLAUDE.md`** | A project-instruction template encoding the whole workflow + folder conventions. |\n| **`docs/`** | The methodology written out: workflows, the CTR model, and best practices. |\n\n## 🚀 Quickstart\n\nThere are two ways to use this — pick one.\n\n### Option A — Install as a plugin (fastest)\n\n```\n/plugin marketplace add AntonioBlago/claude-code-seo-starter\n/plugin install seo-starter@antonioblago\n```\n\nYou get the `/visibly-seo-status-quo`, `/visibly-seo-potential`, `/visibly-seo-offer`, `/visibly-seo-pdf-build` commands, the\nauto-invoked SEO skills, the SEO-intent hook, and the keyless Visibly AI MCP — wired in.\n**No key needed to start** — approve the MCP server and you have the free knowledge tools plus\nthe full local workflow.\n\n**Want the full data engine (live GSC, keywords, backlinks, on-page)?** Add a Visibly AI\nkey — grab one at [visibly-ai.com](https://visibly-ai.com) (~30s, no card), then connect it\nonce (resolves at write time, stays out of git):\n\n```bash\nclaude mcp add --transport http visiblyai https://mcp.visibly-ai.com/mcp --header \"Authorization: Bearer lc_xxxxxxxxxxxxxxxx\"\n```\n\nRestart with `/reload-plugins` if needed. See [`docs/setup.md`](docs/setup.md) for the\npro tier, Google-OAuth (0 credits) and optional DataForSEO wiring.\n\n### Option B — Clone the template\n\nUse the full repo (docs, PDF template, setup script) as a project scaffold.\n\n### 1. Prerequisites\n\n- [Claude Code](https://docs.claude.com/en/docs/claude-code) installed (`npm install -g @anthropic-ai/claude-code`)\n- *(Optional)* a [Visibly AI](https://visibly-ai.com) account for the pro tier — **[sign up free](https://visibly-ai.com)**. Not required: the starter runs keyless.\n- Python 3.11+ (only needed for the PDF / data-crunching helpers)\n\n### 2. Get the blueprint\n\n```bash\n# Use it as a GitHub template, or just clone:\ngit clone https://github.com/AntonioBlago/claude-code-seo-starter.git\ncd claude-code-seo-starter\n```\n\n### 3. (Optional) add your Visibly AI key\n\nSkip this for the free tier — the keyless `.mcp.json` already works. To unlock the\nfull data engine, create a free account at **[visibly-ai.com](https://visibly-ai.com)**,\ncopy your `lc_...` key, and connect it once (resolves at write time, stays out of git):\n\n```bash\nclaude mcp add --transport http visiblyai https://mcp.visibly-ai.com/mcp --header \"Authorization: Bearer lc_xxxxxxxxxxxxxxxx\"\n```\n\nFull tier breakdown, Google-OAuth (live GSC/GA at 0 credits) and optional DataForSEO\nwiring: **[`docs/setup.md`](docs/setup.md)**.\n\n### 4. Launch\n\n```bash\nclaude\n```\n\nOn first run, Claude Code will ask you to approve the Visibly AI MCP server. Approve it, then try:\n\n```\n/visibly-seo-status-quo example.com\n```\n\nThat's it. On the free tier, feed a GSC export to the Python templates; with a key,\ndata is pulled live. Either way you're running the full SEO workflow.\n\n## 🔁 The workflows\n\nEach slash command corresponds to one phase of a real client engagement. They chain:\n\n```\n/visibly-seo-status-quo <domain>   →   /visibly-seo-potential <domain>   →   /visibly-seo-offer <domain>   →   /visibly-seo-pdf-build <script.py>\n   (where do we           (what's the upside,        (what should the          (hand the client a\n    rank today?)           in clicks & €?)            client buy?)              polished PDF)\n```\n\nFull methodology is documented in **[`docs/workflows.md`](docs/workflows.md)**.\n\n## 📈 The CTR model\n\nThe potential analysis is only as good as its click-through-rate curve. This repo ships the **[Keyword Study 2026](https://www.antonioblago.com/keyword-study-2026-organic-search-ctr)** — CTR by position from **first-party Google Search Console data** (1.3M keywords, 94 domains) — instead of the inflated textbook numbers most templates still use.\n\nThe differentiator: the curve is **intent-aware**. A navigational keyword at position 1 earns ~8.9% CTR; an informational one ~3.2%. Forecasting with one blended number quietly mis-states the upside. See **[`docs/ctr-model.md`](docs/ctr-model.md)** for the full intent-by-position table and the Python to apply it. Honest inputs → defensible forecasts → offers that survive scrutiny.\n\n## 🔍 Transparency — what runs where\n\nNo surprises about data flow:\n\n- **Keyless (default):** `.mcp.json` connects to `mcp.visibly-ai.com` without an account. Only the free knowledge tools respond (checklists, guidance, Google guidelines, keyword classification, URL-structure checks) — no client data involved.\n- **With a key:** the data tools (`query_search_console`, `query_analytics`, keywords, backlinks, on-page) route through the Visibly AI backend, hosted on **Railway in the EU**. Your GSC/GA data passes through that backend to reach Claude — that's the product, not a side effect. And it takes **three explicit opt-ins** before a single GSC row can flow: create a Visibly account, add your API key, and connect your Google account via OAuth inside Visibly. Without the Google consent, `query_search_console` has no property to read. Not acceptable for a client? Don't add the key: feed a GSC export to the local Python templates instead — the full workflow still runs.\n- **Permissions:** `.claude/settings.json` auto-allows only metadata and the free knowledge tools. Every tool that reads client data (GSC, GA, keywords, backlinks, on-page, crawling) sits in `ask` — Claude prompts before using it.\n- **The hook** (`.claude/hooks/seo-check.sh`) runs locally, sends nothing anywhere, and only injects a reminder to use real data instead of guessing when your prompt looks SEO-related. Don't want the nudge? Delete the hook.\n\n## 🎨 Customise it\n\nEverything is plain Markdown and shell — fork and adapt:\n\n- **Branding** — edit `CLAUDE.md` and `templates/pdf_example.py` with your colours, fonts, contact block.\n- **Data source** — keyless by default; add a Visibly key for the full engine, or wire your own (GSC export → Python templates, [DataForSEO](https://dataforseo.com/?aff=186597), GA4, Ahrefs…) in `.mcp.json`. See [`docs/setup.md`](docs/setup.md). Free walkthrough for building your own GSC access from scratch: [Indexing Checker für die Google Search Console](https://www.antonioblago.com/de/blog/google-search-console-indexing-performance-checker-skript) (German).\n- **Workflows** — the `.claude/commands/*.md` files *are* the workflows. Rewrite them in your own words.\n- **Guardrails** — extend `.claude/hooks/seo-check.sh` with your own keyword triggers.\n\nSee **[`docs/setup.md`](docs/setup.md)** for a deeper walkthrough and **[`docs/best-practices.md`](docs/best-practices.md)** for the hard-won lessons.\n\n## 📂 Repo layout\n\n```\nclaude-code-seo-starter/\n├── .claude-plugin/           # makes this repo an installable plugin + marketplace\n│   ├── plugin.json           # plugin manifest\n│   └── marketplace.json      # marketplace catalog (one repo = both)\n├── .mcp.json                 # Visibly AI MCP connection — keyless (free tools); add key for pro\n├── server.json               # MCP-registry manifest (publish via mcp-publisher)\n├── .env.example              # copy → .env — optional key + separate data sources\n├── CLAUDE.md                 # project instructions Claude reads on every run\n├── .claude/\n│   ├── commands/             # /visibly-seo-status-quo /visibly-seo-potential /visibly-seo-offer /visibly-seo-pdf-build\n│   ├── skills/               # auto-invoked SEO skills (status-quo, potential, offer, pdf)\n│   ├── hooks/                # seo-check.sh + hooks.json — SEO-intent nudge\n│   └── settings.json         # hook registration + permissions (free tools allowed, data tools ask)\n├── docs/\n│   ├── setup.md              # detailed setup\n│   ├── workflows.md          # the 4-phase methodology\n│   ├── ctr-model.md          # empirical CTR curve\n│   ├── folder-structure.md   # client knowledge base + CI base conventions\n│   ├── best-practices.md     # lessons learned\n│   └── promote.md            # discoverability checklist (registry, awesome lists)\n├── templates/\n│   ├── ci/                       # CI base — brand.py (constants) + CI.md (reference)\n│   ├── client-template/          # copy → clients/<domain>/ (CLAUDE.md + _knowledge/)\n│   ├── status-quo-template.md    # fill-in status-quo skeleton (classification, quick wins)\n│   ├── potential-template.md     # fill-in potential skeleton (deltas, clusters, ROI scenarios)\n│   ├── offer-template.md         # fill-in offer skeleton (phases, pricing, ROI, terms, CTA)\n│   └── pdf_example.py            # minimal CI-PDF starter (fpdf2)\n└── scripts/\n    └── check-setup.sh        # verify your env is wired correctly\n```\n\n## 🤝 Contributing\n\nPRs welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md). Found this useful? A ⭐ helps others find it.\n\n## 📜 License\n\nMIT — see [`LICENSE`](LICENSE). Use it commercially, fork it, ship it for your own clients.\n\n## 💬 Want help setting it up?\n\nIf you'd rather have this dialled in to your agency's workflow — or want to talk SEO, Claude Code, or vibe coding — **[book a consultation](https://calendly.com/antonio-blago/vibe-coding-consultation?back=1&month=2026-06)**.\n\n---\n\n<p align=\"center\">\n  Created by <strong><a href=\"https://antonioblago.de\">Antonio Blago</a></strong> — SEO Freelancer & Neuro-SEO System®<br>\n  <a href=\"https://calendly.com/antonio-blago/vibe-coding-consultation?back=1&month=2026-06\"><strong>📅 Book a consultation</strong></a><br>\n  <sub>If this saves you an afternoon per client, it did its job.</sub>\n</p>\n",
  "bytes": 12211,
  "sha": "645f5ba0eda4ffd73733750839ff2869a34f5ec52f51031cb2104ab05aa6615d",
  "repo_slug": "antonioblago/claude-code-seo-starter",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_antonioblago_visibly_ai_c6c3ba35/readme"
}