How to Build an AI SEO Agent with n8n and ChatGPT: Step-by-Step Tutorial for 2026

Reading Time: 13 minutes

TL;DR

• An AI SEO agent is an automated workflow that connects ChatGPT to SEO data sources – Google Search Console, Semrush, or Ahrefs – and executes tasks like keyword research, content briefing, on-page auditing, and rank reporting without manual input.
• n8n is the best tool for building SEO agents because it connects to any API, runs logic between steps, and works on both cloud and self-hosted infrastructure with no per-task pricing.
• The all-in-one SEO agent in this tutorial handles four tasks: keyword clustering, content brief generation, on-page audit, and automated rank report delivery.
• You need three things before starting: an n8n account (cloud or self-hosted), an OpenAI API key with GPT-4o access, and at least one SEO data source API key (Google Search Console is free).
• Building this agent takes approximately 3 to 4 hours for someone comfortable with n8n’s node editor but new to AI agent workflows.

What Is an AI SEO Agent and How It Differs from a Standard n8n Workflow

An AI SEO agent is an automated workflow where a large language model (LLM) – in this case ChatGPT via the OpenAI API – acts as the reasoning layer between data inputs and task outputs. It does not just move data from one place to another. It reads the data, makes decisions about what to do with it, and produces structured outputs a human or another system can act on.

A standard n8n workflow is deterministic: if X happens, do Y. An AI agent is adaptive: given this data, decide what the best output is and produce it. That distinction matters for SEO because SEO tasks are not purely mechanical. Writing a content brief requires judgment about what to cover and how to structure it. Prioritizing technical audit findings requires understanding which issues actually affect rankings. ChatGPT handles that reasoning layer so the workflow produces usable outputs rather than raw data dumps.

The agent built in this tutorial runs four sub-workflows connected in sequence:

1. Keyword clustering agent – takes a seed keyword list and groups terms by search intent and topic using GPT-4o.
2. Content brief generator – takes the top keyword cluster and produces a structured brief including H2 structure, target questions, and word count guidance.
3. On-page audit agent – pulls page data from Google Search Console and identifies underperforming pages with specific fix recommendations.
4. Rank report agent – compiles outputs from all three agents into a formatted report and delivers it via email or Slack on a schedule.

What You Need Before You Start

Required Accounts and API Keys

• n8n account – cloud (n8n.io) or self-hosted. Cloud trial is free for 14 days. Self-hosted is free forever on your own server.
• OpenAI API key – requires a paid OpenAI account. GPT-4o is recommended for this workflow. Budget approximately $5 to $15/month in API costs for a workflow running weekly across 10 clients (OpenAI, 2024).
• Google Search Console API access – free. Requires a Google Cloud project with the Search Console API enabled and OAuth credentials configured.
• Semrush API key (optional) – required for the keyword clustering agent if you want search volume data alongside GPT-4o clustering. The Guru plan ($249/month) includes API access (Semrush, 2024). You can skip this and use Google Search Console data only for a free alternative.

Required n8n Knowledge

This tutorial assumes you can already: create a workflow, add and connect nodes, configure HTTP Request nodes with API credentials, and use the Expression Editor to pass data between nodes. If any of those are unfamiliar, complete n8n’s official quickstart tutorial before proceeding.

n8n Version

This tutorial was built and tested on n8n version 1.40+ (n8n, 2024). If you are on an older self-hosted version, update before starting – the AI Agent node used in this workflow is not available below version 1.30.

Cloud vs. Self-Hosted n8n: Which to Use for an SEO Agent

Both options work for this tutorial. The choice affects cost, data privacy, and how you handle credentials.

Factor	n8n Cloud	Self-Hosted
Setup time	5 minutes	30-60 minutes
Monthly cost	$20-$50/month	Server cost only (~$5-$20/month on a VPS)
Data privacy	Data processed on n8n servers	All data stays on your server
Maintenance	Zero – n8n manages updates	You manage updates and backups
Execution limits	2,500-10,000 executions/month by plan	Unlimited
Best for	Agencies wanting fast setup	Agencies handling sensitive client data

For most agencies: n8n Cloud is the fastest path to a working agent. Use self-hosted if you handle client data under GDPR or other data residency requirements, or if you expect execution volume above the cloud plan limits.

Setting Up n8n Cloud

Go to n8n.io, create an account, and start a free trial. No configuration needed – you land directly in the workflow editor.

Setting Up n8n Self-Hosted

The fastest self-hosted setup uses Docker. Run the following command on any Linux VPS (Ubuntu 22.04 recommended):

docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -v ~/.n8n:/home/node/.n8n \
  n8nio/n8n

Access the editor at http://your-server-ip:5678. For production use, add an Nginx reverse proxy with SSL. n8n’s official self-hosting documentation covers this in full at docs.n8n.io.

Step 1: Configure Your API Credentials in n8n

Before building any nodes, add all credentials to n8n’s credential store. This keeps API keys out of individual node configurations and allows reuse across workflows.

Add OpenAI Credentials

1. In n8n, go to Settings > Credentials > Add Credential.
2. Search for OpenAI and select it.
3. Paste your OpenAI API key into the API Key field.
4. Name it OpenAI - SEO Agent and save.

Test the connection by clicking Test before saving. A green checkmark confirms the key is valid and has API access.

Add Google Search Console Credentials

Google Search Console uses OAuth2, not a simple API key. Follow these steps:

1. Go to console.cloud.google.com and create a new project named n8n SEO Agent.
2. Enable the Google Search Console API under APIs and Services > Library.
3. Create OAuth credentials: go to APIs and Services > Credentials > Create Credentials > OAuth Client ID. Select Web Application.
4. Add https://your-n8n-domain/rest/oauth2-credential/callback as an authorized redirect URI. For cloud, use your n8n.io subdomain. For self-hosted, use your domain or IP.
5. Copy the Client ID and Client Secret.
6. In n8n, add a new credential, search for Google Search Console, and paste the Client ID and Client Secret.
7. Click Connect and complete the Google OAuth flow in the popup.

Add Semrush Credentials (Optional)

1. In n8n, add a new credential and search for HTTP Header Auth.
2. Name: Semrush API.
3. Header Name: Authorization, Header Value: Bearer YOUR_SEMRUSH_API_KEY.
4. Save.

Semrush does not have a native n8n integration – you will call it via HTTP Request nodes throughout the workflow.

Step 2: Build the Keyword Clustering Agent

The keyword clustering agent takes a list of seed keywords, pulls search volume data (via Semrush or Search Console), and sends everything to GPT-4o to group by search intent and topic.

Node 1: Manual Trigger (or Schedule Trigger)

Add a Manual Trigger node to start. You will convert this to a Schedule Trigger in Step 5 once the workflow is tested. Name it Start - Keyword Clustering.

Node 2: Set Seed Keywords

Add a Set node connected to the trigger. Add a field named keywords with your seed keyword list as a comma-separated string.

Example value:

SEO audit, technical SEO audit, website SEO audit, SEO site audit tool, how to do an SEO audit

Name this node Input - Seed Keywords.

Node 3: Pull Search Volume from Semrush (Optional)

Add an HTTP Request node. Configure it as follows:

• Method: GET
• URL: https://api.semrush.com/
• Query Parameters:
  • type: phrase_these
  • key: {{ $credentials.semrush_api_key }}
  • phrase: {{ $json.keywords }}
  • export_columns: Ph,Nq,Cp,Co
  • database: us

This returns search volume (Nq), CPC (Cp), and competition (Co) for each keyword. Parse the CSV response in the next node.

If skipping Semrush, use Search Console data from Step 3 instead and come back to enrich keyword data later.

Node 4: AI Agent – Keyword Clustering

Add an AI Agent node. This is the core reasoning node. Configure it as follows:

• Credential: OpenAI – SEO Agent
• Model: gpt-4o
• System Prompt:

You are an SEO strategist. Your job is to take a list of keywords and group them into topic clusters based on search intent.

For each cluster:
- Give the cluster a name
- Identify the primary keyword (highest volume, clearest intent)
- List supporting keywords
- Label the intent: informational, commercial, navigational, or transactional
- Recommend a content type: blog post, landing page, product page, or FAQ page

Return your output as valid JSON only. No explanation text outside the JSON.

• User Message:

Here are the keywords with search volume data:

{{ $json.semrush_data }}

Group these into clusters and return the JSON structure described.

• Output Parser: Set to JSON so n8n automatically parses the GPT-4o response into structured data for the next node.

Name this node AI - Keyword Clustering.

Node 5: Set – Store Cluster Output

Add a Set node to store the parsed cluster output in a clean variable for use in the next agent.

• Add field keyword_clusters mapped to {{ $json.output }}.

Name this node Store - Keyword Clusters.

Step 3: Build the Content Brief Generator Agent

The content brief generator takes the top-priority keyword cluster from the previous agent and produces a structured content brief – H2 structure, target questions, word count, and internal link recommendations.

Node 6: Extract Top Cluster

Add a Set node connected to Store - Keyword Clusters.

• Add field top_cluster mapped to {{ $json.keyword_clusters[0] }}.

This selects the first cluster – which GPT-4o returns as the highest-priority group. Name this node Extract - Top Cluster.

Node 7: HTTP Request – Fetch SERP Data

To brief content accurately, the agent needs to know what is currently ranking. Use a SERP API to pull the top 10 results for the primary keyword.

Add an HTTP Request node:

• Method: GET
• URL: https://api.semrush.com/
• Query Parameters:
  • type: phrase_organic
  • key: {{ $credentials.semrush_api_key }}
  • phrase: {{ $json.top_cluster.primary_keyword }}
  • export_columns: Dn,Ur,Fk,Fp
  • database: us
  • display_limit: 10

This returns the top 10 ranking domains, their URLs, and position data for the primary keyword.

Name this node Fetch - SERP Data.

Node 8: AI Agent – Content Brief Generator

Add a second AI Agent node. Configure it:

• Model: gpt-4o
• System Prompt:

You are a senior content strategist specializing in SEO. Your job is to produce detailed content briefs for blog posts and landing pages.

A good content brief includes:
- A working H1 title containing the primary keyword
- A TL;DR block of 4-5 bullet points summarizing the article
- An H2 structure covering all subtopics needed to rank
- H3 subheadings under each H2 where relevant
- A FAQ section with 5 natural-language questions
- Target word count based on competitor content depth
- Content type recommendation
- Internal link opportunities

Return only valid JSON. No text outside the JSON structure.

• User Message:

Primary keyword: {{ $json.top_cluster.primary_keyword }}
Supporting keywords: {{ $json.top_cluster.supporting_keywords }}
Search intent: {{ $json.top_cluster.intent }}
Content type: {{ $json.top_cluster.content_type }}

Top 10 SERP competitors:
{{ $json.serp_data }}

Produce a full content brief for this keyword cluster.

Name this node AI - Content Brief Generator.

Node 9: Store Brief Output

Add a Set node storing the brief:

• Field content_brief mapped to {{ $json.output }}.

Name this node Store - Content Brief.

Step 4: Build the On-Page Audit Agent

The on-page audit agent pulls performance data from Google Search Console, identifies pages with declining clicks or impressions, and sends them to GPT-4o for specific fix recommendations.

Node 10: HTTP Request – Google Search Console Data

Add an HTTP Request node with OAuth2 credentials:

• Method: POST
• URL: https://searchconsole.googleapis.com/webmasters/v3/sites/YOUR_SITE_URL/searchAnalytics/query
• Authentication: OAuth2 – use the Google Search Console credential created in Step 1.
• Body (JSON):

{
  "startDate": "{{ $today.minus(90, 'days').format('YYYY-MM-DD') }}",
  "endDate": "{{ $today.format('YYYY-MM-DD') }}",
  "dimensions": ["page", "query"],
  "rowLimit": 50,
  "orderBy": [{"fieldName": "clicks", "sortOrder": "DESCENDING"}]
}

Replace YOUR_SITE_URL with the property URL exactly as it appears in Search Console (including https://).

This returns the top 50 pages by clicks over the last 90 days with their queries, clicks, impressions, CTR, and average position.

Name this node Fetch - Search Console Data.

Node 11: Code Node – Filter Underperforming Pages

Add a Code node to filter for pages that need attention. Use this JavaScript:

const rows = $input.first().json.rows || [];

const underperforming = rows.filter(row => {
  const ctr = row.ctr;
  const position = row.position;
  const impressions = row.impressions;
  
  // Flag pages with high impressions but low CTR, or position 4-15 (near page one)
  return (impressions > 500 && ctr < 0.03) || (position > 3 && position < 15);
});

return underperforming.map(row => ({ json: row }));

This isolates pages with ranking potential – either sitting just outside page one or ranking but not earning clicks due to weak title or meta description. Name this node Filter - Underperforming Pages.

Node 12: AI Agent – On-Page Audit

Add a third AI Agent node:

• Model: gpt-4o
• System Prompt:

You are a technical SEO specialist. You will receive performance data for underperforming web pages from Google Search Console.

For each page, identify the most likely reason for underperformance and provide specific, actionable fixes.

Possible issues to diagnose:
- Title tag not matching search intent
- Meta description not driving clicks (CTR problem)
- Page ranking for wrong keyword variant
- Content too thin for query competition
- Missing FAQ or structured data opportunity
- Internal link gap

For each page return:
- Page URL
- Primary query it ranks for
- Current position and CTR
- Diagnosed issue
- Specific fix recommendation (be precise - not generic advice)
- Priority: High / Medium / Low

Return as valid JSON array only.

• User Message:

Here are the underperforming pages from Google Search Console:

{{ JSON.stringify($json) }}

Diagnose each page and return fix recommendations.

Name this node AI - On-Page Audit.

Node 13: Store Audit Output

Add a Set node:

• Field audit_findings mapped to {{ $json.output }}.

Name this node Store - Audit Findings.

Step 5: Build the Rank Report Agent and Delivery Node

The rank report agent pulls outputs from all three previous agents and compiles them into a formatted report delivered via email or Slack.

Node 14: Merge – Combine All Agent Outputs

Add a Merge node set to Merge by Position mode. Connect it to:

• Store - Keyword Clusters
• Store - Content Brief
• Store - Audit Findings

This combines all three agent outputs into a single data object for the report generator.

Node 15: AI Agent – Report Compiler

Add a fourth AI Agent node:

• Model: gpt-4o
• System Prompt:

You are an SEO account manager writing a weekly performance and action report for a client.

Write in plain, direct language. No jargon. No filler. The client is a busy business owner who wants to know:
1. What keywords to target this month
2. What content to create first
3. Which pages need fixing and exactly what to fix

Format the report in clean Markdown with clear sections and bullet points.
Do not use phrases like "it's important to note" or "in conclusion".
Keep each section under 150 words.

• User Message:

Keyword clusters identified:
{{ $json.keyword_clusters }}

Content brief for top priority:
{{ $json.content_brief }}

On-page audit findings:
{{ $json.audit_findings }}

Write the weekly SEO report for this client.

Name this node AI - Report Compiler.

Node 16: Deliver Report via Email or Slack

Option A – Email delivery:

Add a Send Email node (using Gmail or SMTP credential):

• To: client@example.com
• Subject: Weekly SEO Report - {{ $today.format('MMMM D, YYYY') }}
• Body: {{ $json.output }}
• Body Content Type: Markdown (if your email provider supports it) or Text.

Option B – Slack delivery:

Add a Slack node:

• Operation: Post Message
• Channel: #seo-reports (or a client-specific channel)
• Message: {{ $json.output }}

Name this node Deliver - Weekly SEO Report.

Node 17: Convert Manual Trigger to Schedule Trigger

Replace the Manual Trigger in Node 1 with a Schedule Trigger:

• Trigger Interval: Weekly
• Day of Week: Monday
• Time: 07:00 AM (client’s timezone)

This runs the full agent workflow every Monday morning and delivers the report before the client’s working day starts.

Step 6: Test, Debug, and Activate the Workflow

Testing Each Agent Individually

Before running the full workflow, test each agent in isolation:

1. Right-click the AI - Keyword Clustering node and select Execute Node. Confirm the JSON output contains clusters with intent labels.
2. Right-click AI - Content Brief Generator and confirm the brief contains an H2 structure and FAQ section.
3. Right-click AI - On-Page Audit and confirm each page has a diagnosed issue and a specific fix.
4. Right-click AI - Report Compiler and confirm the report reads naturally and covers all three sections.

Common Errors and Fixes

Error	Likely Cause	Fix
401 Unauthorized on OpenAI node	API key incorrect or expired	Regenerate key at platform.openai.com and update credential
403 Forbidden on Search Console	OAuth scope missing	Re-authenticate and confirm Search Console API is enabled in Google Cloud
AI Agent returns plain text instead of JSON	System prompt not enforcing JSON output	Add “Return only valid JSON. No text outside the JSON.” as the final line of the system prompt
Merge node produces empty output	One upstream agent failed silently	Check execution log for each agent node individually
Report email not sending	SMTP credentials not configured	Test email credential separately before connecting to workflow

Activating the Workflow

Once all nodes pass individual testing:

1. Run the full workflow once with the Manual Trigger to confirm end-to-end output.
2. Check the delivered report for formatting and accuracy.
3. Switch to Schedule Trigger and click Activate in the top right of the n8n editor.

The workflow is now live and will run automatically every Monday.

How to Scale This Agent Across Multiple Clients

Running this agent for one client is straightforward. Scaling to 10 or 20 clients requires one structural change: parameterization.

Instead of hardcoding the client’s site URL, seed keywords, and delivery email inside the workflow, store all client data in a Google Sheet or Airtable base and loop through it with an n8n Split In Batches node.

Add a Client Config Sheet

Create a Google Sheet with these columns:

client_name	site_url	seed_keywords	report_email	slack_channel
Client A	https://clienta.com	SEO audit, technical SEO	manager@clienta.com	#clienta-seo
Client B	https://clientb.com	link building, backlinks	owner@clientb.com	#clientb-seo

Add a Google Sheets Node at the Start

Replace the seed keyword Set node with a Google Sheets node that reads all rows from the config sheet. Connect it to a Split In Batches node set to batch size 1. The rest of the workflow then runs once per client row, with all hardcoded values replaced by {{ $json.site_url }}, {{ $json.seed_keywords }}, and so on.

This turns a single-client workflow into an agency-wide SEO agent that runs automatically across your full client base every Monday morning.

Frequently Asked Questions About Building AI SEO Agents with n8n

What is an AI SEO agent and how is it different from basic SEO automation?

An AI SEO agent combines automation with AI reasoning. Basic SEO automation moves data between tools on a schedule – pulling rank data into a spreadsheet, for example. An AI SEO agent uses a large language model like GPT-4o as a reasoning layer that interprets that data, makes decisions about it, and produces structured outputs like content briefs, audit recommendations, or written reports. The agent handles tasks that require judgment, not just data transfer.

Do I need coding skills to build this workflow in n8n?

No coding is required for most of this workflow. The only exception is the JavaScript filter in the Code node in Step 4, which is included in full in this tutorial and can be copied directly. Everything else is configured through n8n’s visual node editor. Familiarity with n8n’s Expression Editor for passing data between nodes is needed – if that is new, spend 30 minutes with n8n’s quickstart guide first.

How much does running this AI SEO agent cost per month?

The main cost is OpenAI API usage. A workflow covering keyword clustering, content briefing, on-page audit, and report generation for one client uses approximately 8,000 to 15,000 tokens per run with GPT-4o. At GPT-4o pricing of $0.005 per 1,000 input tokens and $0.015 per 1,000 output tokens, one full run costs approximately $0.12 to $0.25 per client (OpenAI, 2024). Running weekly for 10 clients costs roughly $5 to $10/month in API costs, plus n8n Cloud at $20-$50/month if you are not self-hosting.

Can I use a different AI model instead of GPT-4o?

Yes. n8n’s AI Agent node supports Anthropic Claude, Google Gemini, and any OpenAI-compatible API endpoint. Claude 3.5 Sonnet is a strong alternative for the content brief and report compilation nodes because it follows structured output instructions reliably and produces cleaner Markdown formatting. Swap the model in the AI Agent node credential settings without changing anything else in the workflow.

How do I handle Google Search Console authentication for multiple client sites?

Each client site requires its own Google Search Console OAuth credential in n8n. Create a separate credential per client and reference the correct one in the Search Console node using n8n’s credential parameter expressions. If managing 10+ clients, a Google Service Account with domain-wide delegation is a more scalable approach than individual OAuth connections – Google’s Search Console API documentation covers service account setup.

What happens if the AI agent returns badly formatted JSON?

Add an n8n Code node after each AI Agent node to validate and clean the JSON output before passing it downstream. A simple validation looks like this:

try {
  const parsed = JSON.parse($input.first().json.output);
  return [{ json: parsed }];
} catch(e) {
  return [{ json: { error: 'JSON parse failed', raw: $input.first().json.output } }];
}

This catches parse failures and routes them to an error handler rather than silently breaking the next node in the workflow.

Can this workflow replace an SEO analyst entirely?

No. The agent handles data collection, pattern recognition, and structured output generation – the repeatable process layer of SEO work. It does not replace strategic decisions: which market to target, how to position a client’s content against a dominant competitor, or how to explain a ranking loss to a client and rebuild their confidence. The agent frees the analyst from the process layer so they can spend more time on those judgment calls.

Key Takeaways

• An AI SEO agent built in n8n connects ChatGPT to your SEO data sources and automates four tasks in sequence: keyword clustering, content brief generation, on-page auditing, and report delivery – running automatically on a weekly schedule.
• Use n8n Cloud for fast setup with no maintenance overhead. Use self-hosted n8n for client data that cannot leave your own infrastructure.
• The JSON output format is the most critical configuration in every AI Agent node – set it explicitly in the system prompt and validate it with a Code node before passing data downstream.
• Scale the workflow from one client to twenty by parameterizing all client-specific values in a Google Sheet and looping through them with n8n’s Split In Batches node.
• API costs for this full workflow run approximately $0.12 to $0.25 per client per week using GPT-4o – making it one of the most cost-efficient SEO automation builds available at agency scale.