Practitioner SEO

An opinionated, evidence-based SEO toolkit for Claude Desktop.

Three skills. One MCP server. One methodology. No checklists.

---

What this is

Practitioner SEO gives Claude a complete SEO workflow:

1. Page Optimizer -- give it a URL, get back a diagnostic and a copy-ready optimization plan with tiered actions
2. Content Strategist -- find content gaps, diagnose clusters, audit competitors across three operating modes
3. Page Writer -- give it a keyword, get back a publish-ready page with schema, FAQ, and reverse link table written in your voice

The skills share a single evidence-based methodology (SEO_METHODOLOGY.md) and a single MCP server (practitioner-seo) that handles all API integrations.

Every recommendation cites its evidence. Every output includes an honest assessment of what optimization can and cannot achieve for that specific query.

---

Prerequisites

• Claude Desktop (Pro subscription or higher) or Claude Code
• Python 3.10+
• pip or uv for package management
• API keys (some optional, all free or low-cost):
  • SerpAPI key (required for SERP analysis and keyword research)
  • Google Search Console access (required for GSC data; free)
  • PageSpeed Insights API key (required for Core Web Vitals; free)

---

Quickstart

1. Install the MCP server

pip install practitioner-seo

Or from source:

git clone https://github.com/your-org/practitioner-seo.git
cd practitioner-seo/mcp-server
pip install -e .

2. Configure API keys

Create ~/.practitioner-seo/config.yaml:

serpapi_key: "your-serpapi-key"
pagespeed_key: "your-pagespeed-key"

gsc:
  auth_method: "oauth"
  client_id: "your-google-client-id"
  client_secret: "your-google-client-secret"

See docs/API_KEYS.md for where to get each key. See docs/GSC_SETUP.md for the full Google Search Console setup walkthrough.

3. Connect to Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "practitioner-seo": {
      "command": "practitioner-seo"
    }
  }
}

If you installed with uv instead of pip:

{
  "mcpServers": {
    "practitioner-seo": {
      "command": "uvx",
      "args": ["practitioner-seo"]
    }
  }
}

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

4. Set up your site

Copy the files from skills/ and templates/ into a Claude Project:

skills/
  SEO_METHODOLOGY.md
  OPTIMIZER_PROTOCOL.md
  STRATEGIST_PROTOCOL.md
  WRITER_PROTOCOL.md
  ONBOARDING.md

Then tell Claude: "Set up Practitioner SEO"

The onboarding skill will walk you through a structured interview, analyze your writing voice, and generate your site configuration files.

5. Start using it

After onboarding, you can:

• "Optimize benchcraftworkshop.com/best-hand-planes/" -- runs the full optimizer protocol
• "What should I write next?" -- runs a site-wide gap audit
• "Write a post about sharpening Japanese chisels" -- researches and drafts a complete page

---

Architecture

+------------------+     +-------------------+     +------------------+
|  Claude Desktop  |     |   Skills (MD)     |     |  Site Config     |
|  or Claude Code  |<--->|  Optimizer        |<--->|  SITE_CONFIG.md  |
|                  |     |  Strategist       |     |  VOICE_GUIDE.md  |
|                  |     |  Writer           |     |  SITE_CONTEXT.md |
|                  |     |  Onboarding       |     |  FORBIDDEN.md    |
+------------------+     +-------------------+     +------------------+
        |
        | MCP (stdio)
        |
+-------v----------+
|  practitioner-seo |
|  MCP Server       |
|                   |
|  8 tools:         |
|  - fetch_page     |
|  - scrape_url     |
|  - get_gsc_data   |
|  - keyword_rankings|
|  - get_serp       |
|  - get_pagespeed  |
|  - pillar_research|
|  - content_brief  |
+-------------------+
        |
        | APIs
        |
+-------v-------------------------------------------+
|  Google Search Console  |  SerpAPI  |  PageSpeed  |
+-------------------------+-----------+-------------+

Layer 1: Methodology (SEO_METHODOLOGY.md) -- the evidence base. Universal. Ships as an opinionated default. Advanced users can override specific claims via SITE_CONFIG.methodology_overrides.

Layer 2: Protocols (Optimizer, Strategist, Writer) -- execution instructions. Universal but parameterized. They reference {SITE_CONFIG.*} variables that are populated per-site during onboarding.

Layer 3: Site Config -- per-site configuration generated by onboarding. Voice guide, forbidden words, site context, formatting rules, commercial model, CMS quirks.

---

Graceful degradation

Every tool checks its API key at call time. Missing keys produce structured error messages with setup instructions, not crashes.

Missing	What happens
SerpAPI key	SERP/pillar tools fall back; skills use web_search
PageSpeed key	CWV section skipped; manual URL provided
GSC credentials	GSC sections skipped; setup recommended
MCP server itself	Skills note tools are unavailable; core logic still runs

You can start using the skills with zero API keys configured. You'll get progressively better output as you add each integration.

---

Example site

The examples/ directory contains a fully worked example using the fictional site benchcraftworkshop.com (a woodworking tool review site by a professional furniture maker). Every configuration file is populated to show what "done" looks like:

• example-site-config.md -- complete SITE_CONFIG
• example-voice-guide.md -- extracted voice patterns
• example-forbidden.md -- site-specific forbidden words
• example-site-context.md -- 20 pages with link relationships
• example-formatting-rules.md -- woodworking niche conventions

---

Documentation

• docs/SETUP.md -- detailed installation and Claude Desktop configuration
• docs/GSC_SETUP.md -- Google Search Console OAuth walkthrough
• docs/API_KEYS.md -- where to get SerpAPI and PageSpeed Insights keys
• docs/TROUBLESHOOTING.md -- common issues and fixes
• docs/CUSTOMIZATION.md -- how to override methodology defaults

---

License

MIT