# How to build an SEO agent with Claude Code and MCP: a six-step walkthrough for small teams

> Build your first SEO agent in six steps: connect Search Console through MCP, write the rules, split work into subagents, add hooks, and schedule it.

Source: https://contengi.com/blog/how-to-build-an-seo-agent
Author: Stefan Maritz
Published: 2026-11-12

The wiring takes an afternoon, the rules take weeks, and the rules are what make the agent sound like you.

**TL;DR**

-   To build an SEO agent, pick one job, connect your data through MCP, write the rules down as instructions and skills, and put a review gate in front of anything that publishes.
-   Claude Code is the most flexible place to build one: it reads files, runs commands, connects to MCP servers, and supports subagents, hooks, and scheduled tasks.
-   Search Console is the first connection to make, followed by a keyword source and a way to read the live results page.
-   Subagents keep noisy research out of the main conversation, and hooks run checks automatically after every edit, so the linter never gets skipped.
-   The wiring takes an afternoon. The rules take weeks, and they decide whether the output sounds like you.

Building an SEO agent sounds like a job for a developer with a hoodie and a standing desk. In 2026 it's closer to setting up a new phone: connect your accounts, write down how you like things, and spend the next month correcting its habits.

This walkthrough builds one agent for one job, a weekly striking-distance report, using Claude Code and MCP. Once that runs clean, the same pattern stretches to briefs, drafts, and refresh plans. If you want the bigger picture first, start with [what an AI SEO agent is](https://contengi.com/blog/ai-seo-agent).

## What do you need to build an SEO agent?

You need five pieces: a runtime, data connections, written rules, a way to split work, and guardrails. Here's how they map to Claude Code.

Piece

In Claude Code

What it does for SEO

Runtime

Claude Code in the terminal, IDE, desktop app, or browser

Plans the work, reads files, runs commands

Data

MCP servers

Pulls Search Console, keyword data, and results pages

Rules

CLAUDE.md and skills

Holds your process, tone, and banned phrases

Workers

Subagents

Runs research in a separate context so the main session stays clean

Guardrails

Hooks

Runs your linter or blocks risky commands automatically

[Claude Code reads your codebase, edits files, runs commands, and integrates with your development tools](https://docs.claude.com/en/docs/claude-code/overview), in the terminal, an IDE, a desktop app, or the browser. For SEO, "codebase" just means a folder with your rules, your exports, and your drafts.

## Step 1: pick one job and write down how you do it

Choose a job you already do by hand every week. Striking-distance analysis is ideal: pull queries in positions 11 to 20, group them by page, and decide one change per page.

Write the steps exactly as you do them, judgement calls included. "Ignore branded queries" and "skip pages we plan to retire" are the instructions that turn a pile of rows into a useful report.

## Step 2: connect your data with MCP

Claude Code talks to outside tools through MCP, and [HTTP servers are the recommended option for connecting to remote MCP servers](https://docs.claude.com/en/docs/claude-code/mcp). Connect Search Console first with a [Google Search Console MCP](https://contengi.com/blog/google-search-console-mcp), because it's the only source that knows your site.

Add a keyword source next. A [DataForSEO MCP](https://contengi.com/blog/dataforseo-mcp) is the pay-as-you-go route, and if you already pay for a suite, compare the [Ahrefs and Semrush MCP servers](https://contengi.com/blog/ahrefs-mcp-vs-semrush-mcp) before you choose.

## Step 3: write the rules in CLAUDE.md and a skill

[CLAUDE.md is a file Claude Code reads at the start of every session](https://docs.claude.com/en/docs/claude-code/overview), which makes it the right home for standing rules: your audience, tone of voice, link policy, and the words you never use.

The job itself goes into a skill, a packaged workflow you trigger with a slash command such as /striking-distance. Keep the skill short and specific: inputs, steps, output format, and what to do when data is missing. A set of [content marketing skills for Claude](https://contengi.com/blog/content-marketing-skills-for-claude) makes a decent starting shelf to edit from.

## Step 4: split the work into subagents

Each subagent [runs in it's own context window with a custom system prompt, specific tool access, and independent permissions](https://docs.claude.com/en/docs/claude-code/sub-agents). For SEO that means a research subagent can read a 5,000-row Search Console export and hand back a one-page summary, without flooding your main session.

Subagents are markdown files with a short header. Have the main session save the export through the Search Console MCP, then hand it to a read-only worker like this one:

```
---
name: gsc-researcher
description: Groups striking-distance queries from a Search Console export by page. Use for weekly SEO reports.
tools: Read, Grep, Glob
model: haiku
---
Read data/gsc-90-days.csv.
Keep queries in positions 11 to 20.
Drop branded queries and any query longer than 12 words.
Group by page. Return one suggested change per page.
```

Routing a worker like this to a smaller, cheaper model keeps the bill down, and limiting its tools means it can't edit a file even if it wants to.

## Step 5: add a quality gate with hooks

[Hooks run code at key points in Claude Code's lifecycle](https://docs.claude.com/en/docs/claude-code/hooks-guide), such as formatting files after an edit or blocking a command before it runs. Point one at your banned-word linter so every draft gets checked the moment it's saved, and block any command that publishes without your approval.

No linter of your own yet? Paste drafts into the [AI slop cleaner](https://contengi.com/ai-slop-cleaner) until you build one. Every AI-generated page needs to be [manually fact-checked and reviewed for accuracy before publishing](https://developers.google.com/search/docs/fundamentals/using-gen-ai-content), and that review stays with you.

## Step 6: put it on a schedule

Once the report runs clean three weeks in a row, schedule it. [Cloud scheduled tasks run in the cloud, so they keep running when your computer is off](https://docs.claude.com/en/docs/claude-code/overview). Monday morning, the report is waiting.

## What we learned building ours

The wiring took an afternoon. The rules took weeks of reading output and writing "no, not like that" into the instructions file.

The biggest surprise came from Search Console itself. When our agent pulled 90 days of contengi.com queries, a few weren't queries at all: one was an entire marketing persona, job title and pain points included, typed into Google as a single search. No founder searches like that, so our read is that visibility tools are testing prompts against the results page. That's why the example above drops anything longer than 12 words. Without that rule, the agent kept recommending we optimise for robots.

## Should you build or buy an SEO agent?

Build if you're comfortable in a terminal and enjoy tuning a system. Buy if you'd rather spend the hours on content. The cost after launch is mostly maintenance: MCP servers update, rules drift, and someone has to notice when a scheduled task loses access to Search Console.

New to the terminal but curious? Start with [Claude Code for marketers](https://contengi.com/blog/claude-code-for-marketers). If you want the agents without the upkeep, Contengi runs this same pattern out of the box, with the knowledge base, linter, link checks, and Search Console reads already wired, and the [agentic SEO platforms](https://contengi.com/blog/best-agentic-seo-platforms) roundup compares it with the alternatives.

## Frequently asked questions

### How do I build an SEO agent?

Pick one weekly job, connect Search Console and a keyword source through MCP, and write your rules in CLAUDE.md and a skill. Then move research into subagents, add hooks that lint every draft, and review each output before anything publishes.

### Can I build an SEO agent without coding?

Mostly, yes. Claude Code takes plain-language instructions and writes its own config files, so you need comfort with folders and a terminal or the desktop app, not a programming background. If even that is too much, a platform with the agents pre-built is the faster route.

### Which MCP servers does an SEO agent need?

Search Console first, because it's the only source with your own rankings. Add a keyword source such as DataForSEO, Ahrefs, or Semrush next, plus a way to read the live results page for briefs.

### What's the difference between an SEO agent and SEO automation?

[SEO automation](https://contengi.com/blog/seo-automation) runs the same fixed steps every time, like a scheduled export. An agent chooses its steps based on what it finds, so it can skip a page with no data or dig into one that dropped.

### How long does it take to build an SEO agent?

An afternoon for the connections and a first working run. Expect three or four weeks of correcting the rules before the output needs only light edits.
