Installation

Get SEO Machine running in your environment with this comprehensive installation guide.

Prerequisites

Before you begin, ensure you have:

Claude Code

Claude Code installed and configured

Python 3.8+

Python 3.8 or higher for analysis modules

Anthropic API Account

Active Anthropic API account for Claude Code

Git

Git for cloning the repository

Step 1: Clone the Repository

Clone the SEO Machine repository to your local machine:

git clone https://github.com/[your-username]/seomachine.git
cd seomachine

Replace [your-username] with the actual GitHub username or organization hosting the repository.

Step 2: Install Python Dependencies

SEO Machine includes powerful Python analysis modules that require several packages. Install them using pip:

pip install -r data_sources/requirements.txt

What Gets Installed

The requirements file includes:

Google Analytics & Search Console

google-analytics-data>=0.18.0
google-auth>=2.23.0
google-auth-oauthlib>=1.1.0
google-api-python-client>=2.100.0

For GA4 traffic data and Search Console rankings.

Data Analysis

pandas>=2.1.0
numpy>=1.24.0
scikit-learn>=1.3.0

For keyword clustering, topic analysis, and opportunity scoring.

NLP & Text Analysis

textstat>=0.7.3
nltk>=3.8.0

For readability scoring (Flesch Reading Ease, grade level) and text analysis.

Web Scraping

beautifulsoup4>=4.12.0
lxml>=4.9.0
requests>=2.31.0

For fetching and analyzing competitor content.

Configuration & Utilities

python-dotenv>=1.0.0
diskcache>=5.6.0
markdown>=3.5.0

For environment variables, API response caching, and WordPress publishing.

Using a virtual environment is recommended to avoid dependency conflicts:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r data_sources/requirements.txt

Step 3: Open in Claude Code

Open the SEO Machine workspace in Claude Code:

claude-code .

This launches Claude Code with the SEO Machine workspace loaded, giving you access to all custom commands, agents, and context files.

If claude-code command is not found, ensure Claude Code is properly installed and added to your PATH.

Step 4: Directory Structure Verification

Verify that all required directories exist. SEO Machine should have this structure:

seomachine/
├── .claude/
│   ├── commands/          # Custom workflow commands
│   ├── agents/            # Specialized analysis agents
│   └── skills/            # 26 marketing skills
├── data_sources/          # Analytics integrations
│   ├── modules/          # Python analysis modules
│   ├── config/           # API credentials (create this)
│   ├── utils/            # Helper functions
│   └── cache/            # Cached API responses (create this)
├── config/                # Configuration files
├── context/               # Brand guidelines and context
├── wordpress/             # WordPress integration files
├── topics/                # Raw topic ideas
├── research/              # Research briefs
├── drafts/                # Work in progress
├── review-required/       # Pending review
├── published/             # Final content
├── rewrites/              # Updated content
├── landing-pages/         # Landing pages
└── audits/                # Audit reports

Create any missing directories:

mkdir -p data_sources/config data_sources/cache
mkdir -p topics research drafts review-required published rewrites landing-pages audits

Step 5: Configure API Integrations (Optional)

SEO Machine can integrate with external data sources for enhanced capabilities. These integrations are optional but recommended for data-driven content strategy.

Google Analytics 4

Create Service Account

Go to Google Cloud Console
Create a new project or select an existing one
Enable the Google Analytics Data API
Navigate to APIs & Services > Credentials
Create a Service Account
Download the JSON key file

Grant Access

Open your GA4 property
Go to Admin > Property Access Management
Add the service account email (from JSON file)
Grant Viewer role

Save Credentials

Save the JSON key file to:

credentials/ga4-credentials.json

Google Search Console

Enable API

In Google Cloud Console (same project as GA4)
Enable the Google Search Console API

Grant Access

Open Google Search Console
Select your property
Go to Settings > Users and permissions
Add the service account email
Grant Full permission

Save Credentials

You can use the same JSON file as GA4:

credentials/gsc-credentials.json

DataForSEO

Create an account at DataForSEO

Get API Credentials

Log in to your DataForSEO dashboard
Navigate to API credentials
Copy your login email and password

Create Environment File

Create a .env file in data_sources/config/ with your credentials:

cp .env.example data_sources/config/.env

Then edit data_sources/config/.env:

# Google Analytics 4
GA4_PROPERTY_ID=123456789
GA4_CREDENTIALS_PATH=./credentials/ga4-credentials.json

# Google Search Console
GSC_SITE_URL=https://yoursite.com/
GSC_CREDENTIALS_PATH=./credentials/gsc-credentials.json

# DataForSEO
DATAFORSEO_LOGIN=[email protected]
DATAFORSEO_PASSWORD=your_api_password_here

# Optional: Blog path filter
BLOG_PATH=/blog/

# Company information
COMPANY_NAME=Your Company Name
COMPANY_DOMAIN=yoursite.com
TARGET_INDUSTRY=your-industry

Never commit your .env file to version control! It contains sensitive API credentials. The .env file is already in .gitignore.

Test API Connectivity

Verify your API integrations are working:

python3 test_dataforseo.py

This script tests connectivity to DataForSEO and displays your account balance and available credits.

Step 6: WordPress Integration (Optional)

To publish directly to WordPress from SEO Machine:

Install MU Plugin

Copy wordpress/seo-machine-yoast-rest.php to your WordPress site:

wp-content/mu-plugins/seo-machine-yoast-rest.php

This plugin exposes Yoast SEO fields via the WordPress REST API.

Add Functions Snippet

Add the code from wordpress/functions-snippet.php to your theme’s functions.php file.

Create Application Password

In WordPress admin, go to Users > Your Profile
Scroll to Application Passwords
Create a new application password
Copy the generated password

Configure Credentials

Add to your data_sources/config/.env file:

WP_URL=https://yoursite.com
WP_USERNAME=your_username
WP_APP_PASSWORD=your_application_password

See wordpress/README.md for detailed setup instructions.

Verification

Verify your installation is complete:

Check Python Dependencies

python -c "import pandas, nltk, textstat, sklearn; print('All dependencies installed!')"

Verify Directory Structure

ls -la .claude/commands/
ls -la data_sources/modules/

Test Claude Code Commands

In Claude Code, type / to see available commands. You should see:

/research
/write
/optimize
/analyze-existing
And more…

Troubleshooting

Python dependencies fail to install

Issue: Error installing packages from requirements.txtSolution:

Ensure Python 3.8+ is installed: python --version
Upgrade pip: pip install --upgrade pip
Install packages individually to identify the problem
Check for system dependencies (some packages require compilers)

Claude Code commands not appearing

Issue: Slash commands don’t show up in Claude CodeSolution:

Ensure you opened Claude Code from the repository root directory
Check that .claude/commands/ directory exists with .md files
Restart Claude Code
Verify Claude Code is up to date

API authentication errors

Issue: Google Analytics or Search Console API calls failSolution:

Verify the service account JSON file exists at the specified path
Check that the service account has been added to GA4/GSC with correct permissions
Ensure the property ID and site URL in .env are correct
Run python3 test_dataforseo.py to test connectivity

Module import errors

Issue: Python scripts fail with “ModuleNotFoundError”Solution:

Activate your virtual environment if using one
Reinstall requirements: pip install -r data_sources/requirements.txt
Check that you’re running scripts from the repository root
Verify Python path includes the repository directory

Next Steps

With SEO Machine installed, you’re ready to configure your context files and create your first article.

Configuration

Set up brand voice, style guide, and SEO guidelines

Quick Start

Create your first SEO-optimized article in 10 minutes

Getting Started

Core Concepts

Workflows

Commands

Advanced Commands

Agents

Data Sources

Integrations

Installation

Installation

Prerequisites

Claude Code

Python 3.8+

Anthropic API Account

Git

Step 1: Clone the Repository

Step 2: Install Python Dependencies

What Gets Installed

Step 3: Open in Claude Code

Step 4: Directory Structure Verification

Step 5: Configure API Integrations (Optional)

Google Analytics 4

Google Search Console

DataForSEO

Create Environment File

Test API Connectivity

Step 6: WordPress Integration (Optional)

Verification

Troubleshooting

Next Steps

Configuration

Quick Start

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Workflows

Commands

Advanced Commands

Agents

Data Sources

Integrations

​Installation

​Prerequisites

Claude Code

Python 3.8+

Anthropic API Account

Git

​Step 1: Clone the Repository

​Step 2: Install Python Dependencies

​What Gets Installed

​Step 3: Open in Claude Code

​Step 4: Directory Structure Verification

​Step 5: Configure API Integrations (Optional)

​Google Analytics 4

​Google Search Console

​DataForSEO

​Create Environment File

​Test API Connectivity

​Step 6: WordPress Integration (Optional)

​Verification

​Troubleshooting

​Next Steps

Configuration

Quick Start

Build docs developers (and LLMs) love

Installation

Prerequisites

Step 1: Clone the Repository

Step 2: Install Python Dependencies

What Gets Installed

Step 3: Open in Claude Code

Step 4: Directory Structure Verification

Step 5: Configure API Integrations (Optional)

Google Analytics 4

Google Search Console

DataForSEO

Create Environment File

Test API Connectivity

Step 6: WordPress Integration (Optional)

Verification

Troubleshooting

Next Steps