SiteGraph SEO Agent

Find the pages that are holding your WordPress site back, get a prioritized plan to fix them, and let Claude do the fixing — with a diff you approve and one-click undo.

SiteGraph is a WordPress plugin plus a set of Claude skills. The plugin reads your content straight from the database, maps every internal link, merges in your Google Search Console data, and scores every page from 0 to 100 with the reasons it is weak. It then exposes all of that — and a safe way to change things — to AI agents over MCP.

Why this exists

The official WordPress MCP Adapter, the WordPress.com connector and the general-purpose MCP plugins give an agent access: read a post, update a post. That is plumbing. On its own it does not tell the agent which of your 400 pages deserve attention, why, or what change would help — and a raw "update post" tool is a risky thing to hand to an agent on a live site.

SiteGraph sits on top of that plumbing (it is built on the core Abilities API and the official MCP Adapter) and adds the two missing pieces:

1. Judgment — a site-wide link graph and page scores, joined with search demand, turned into a ranked action plan.

2. Safety — agents can only propose changesets. You see a before/after diff, approve it, and can undo or redo it at any time. Undo refuses to overwrite edits made after the change.

What it replaces

It does not replace keyword research or backlink tools (Ahrefs, Semrush): it works on what you control on your own site.

Questions it answers that other tools can't

Because it sees your internal links, your content, your search data and can act, an agent with SiteGraph can answer things like:

• "Which pages get search impressions but have zero internal links pointing to them?"

• "I have an hour this week. Which five changes would help the most?"

• "Which existing sentences on my site could link to this page, and with what anchor?"

• "Which pages rank on page one but get far fewer clicks than they should?"

• "Which two pages are competing for the same topic?"

• "Undo the links you added yesterday, but keep the meta descriptions."

• "Did the links we added last month move those pages?"

Related MCP server: Agent Abilities for MCP

How it works

flowchart LR
    DB[(WordPress<br/>database)] --> G[Link graph<br/>inbound · depth · broken]
    GSC[Search Console<br/>Pages export] --> S
    G --> S[Page scores<br/>0–100 + reasons]
    S --> P[Action plan<br/>ranked tasks]
    P --> A[Agent proposes<br/>changeset]
    A --> R{You review<br/>the diff}
    R -- approve --> AP[Applied]
    R -- reject --> D[Discarded]
    AP -- undo --> U[Undone]
    U -- redo --> AP
    AP --> M[Impact: before vs now]

1. Scan (scan-site) — parses every published page's content, resolves each internal link to a post, and computes inbound links, outbound links, broken links and click depth from the home page (following content links, menus and paginated category archives). Nothing is crawled and nothing is changed.

2. Search data (import-search-data) — upload the Search Console Pages CSV in wp-admin, or let the agent push rows from a Search Console connector. Rows are matched by URL path, so a production export works on staging.

3. Score — each page starts at 100 and loses points per issue (see Scoring).

4. Plan (get-action-plan) — groups pages into tasks, ranked by impact, search demand at stake and effort. Each task says whether an agent can do it, what tools to use, and a prompt you can give the agent.

5. Change — the agent proposes a changeset; you approve; it is applied atomically, recorded, and reversible.

A typical session with Claude

On the demo site in this repository (39 pages, three months of Search Console data):

You: Audit my site with SiteGraph and tell me what to fix first.

Claude: I scanned 39 pages. Average score is 73; 12 pages are weak or critical, 10 are orphans (no internal links), and 1 internal link is broken. The three changes that matter most:

1. Link to 10 orphan pages — they have 28,200 impressions between them but no page links to them. Top ones: Trail Running Shoes vs Hiking Boots (9,100 impressions), Sleeping Bag Temperature Ratings Explained (8,800). I can do this.

2. Push 11 pages from page 2 into the top 10 — e.g. How to Waterproof a Tent at position 11.8 with 6,400 impressions. Internal links from your strongest tent pages should help.

3. Rewrite two search snippets — Best Lightweight Backpacking Tents of 2026 ranks at 3.2 but gets 1.4% CTR, where results usually get ~10%.

Want me to propose the internal links for the orphan pages? I'll show you every change before anything is applied.

You: Yes, start with the temperature ratings page.

Claude: Changeset #4 links it from three sleep guides that already use the phrase — for example on Sleeping Pad R-Values: "Like sleeping bag temperature ratings, R-values are lab numbers…". Nothing has changed yet. Apply it?

You: Apply.

Claude: Applied. The page now has 3 internal links and is no longer an orphan. Say "undo changeset #4" or click Undo in wp-admin to revert it exactly.

The conversation above is illustrative; the numbers are the real output of the tools on the demo site.

Screens

Weak pages — weakest first, with the reasons

Page report — why a page is weak, and which pages could link to it

The suggestions are existing sentences on related pages. Select them and propose a changeset without leaving wp-admin.

Action plan — what to do, why, how long it takes, and whether an agent can do it

Review before anything changes

Undo and redo, with history and impact

Link graph

Rings show click depth from the home page; colors show page scores; pages outside the dashed ring cannot be reached by clicking.

Quick start

Requirements

• WordPress 6.9 or newer (for the Abilities API) and PHP 7.4+

• The MCP Adapter plugin, so agents can connect

• HTTPS on live sites (Application Passwords require it)

1. Install the plugin

Copy the sitegraph-seo-agent folder to wp-content/plugins/ (or zip it and upload it under Plugins → Add New → Upload), then activate it. Open SiteGraph SEO in wp-admin and click Scan site.

2. Add Search Console data (recommended)

Search Console → Performance → Search results → pick a date range → Export → Download CSV. Upload Pages.csv from the zip on the SiteGraph Overview screen.

3. Generate a connection

Open SiteGraph SEO → Connect an agent and click Generate a connection. It creates a revocable Application Password and shows, once, the MCP URL and an access token.

4. Install the SiteGraph SEO plugin for Claude Code

The Claude plugin connects Claude to your site and adds skills for the workflow: audit → plan → propose → review → apply, and when to stop and ask you. In Claude Code:

/plugin marketplace add am333ni7y/sitegraph-seo-agent
/plugin install sitegraph-seo@sitegraph

Claude Code asks for the MCP URL and access token when you enable it; the token goes to your system's secure credential store. Then ask: "Audit my site with SiteGraph and tell me the five changes that would help most."

Prefer to connect without the plugin? The Connect screen also shows a ready claude mcp add --transport http sitegraph <MCP URL> --header "Authorization: Basic <token>" command.

Other MCP clients (Cursor, VS Code, Claude Desktop through a proxy) can use the same endpoint; the MCP Adapter docs cover client configuration.

MCP tools

All tools are WordPress abilities in the sitegraph/ namespace, exposed on a dedicated MCP server at /wp-json/sitegraph/v1/mcp (tool names use -, e.g. sitegraph-scan-site). They are also discoverable through the MCP Adapter's default server.

Changeset operations: add_internal_link (wrap an existing phrase in a link — never inside headings or existing links), replace_text, set_post_title, set_seo_title, set_meta_description. SEO fields are written to Yoast SEO, Rank Math or SEOPress when active; otherwise SiteGraph prints the title tag and meta description itself.

Scoring

Every page starts at 100. Issues subtract points; the most damaging are listed first.

Scores of 0–39 are critical, 40–59 weak, 60–79 fair, 80–100 good. The score is a way to prioritize work on your site, not a Google metric. The home page, blog index and privacy policy are exempt from the link and length checks.

Safety model

• Real user, real permissions. The agent authenticates as your WordPress user with an Application Password. Tools require edit_others_posts (Editors and Admins; filter sitegraph_capability), and every write also checks edit_post for each post.

• Narrow writes. Five operation types; writes are limited to post content, post title and the SEO title/description fields of supported SEO plugins. No raw SQL, no arbitrary meta, no deletes.

• Propose → review → apply. Proposals never change content. Apply, undo and redo carry MCP destructiveHint, so clients ask before running them.

• Exact, conflict-safe undo. Changesets store the exact before/after of every field. Undo and redo refuse when content changed in the meantime and name the newer changeset that touched it; force exists but the skills only use it after you explicitly agree.

• History. Who proposed, applied, undid and redid what, and when. WordPress revisions are still created as usual.

See SECURITY.md and the privacy policy: SiteGraph has no server of its own, sends no telemetry, and the author receives no data.

Try the demo locally

The demo/ folder seeds an outdoor-gear blog ("Northwind Outdoor Journal", 32 posts and 7 pages) with realistic problems: orphans, thin pages, broken links, two cannibalizing tent lists, buried pages, and a Search Console export with low-CTR and striking-distance pages.

php demo/seed-demo-site.php /path/to/wordpress --yes-wipe   # local/dev sites only; replaces posts and pages
php demo/demo-changesets.php /path/to/wordpress             # scan, import search data, create sample changesets
php tests/run-integration.php /path/to/wordpress            # 68 end-to-end checks through the Abilities API

CI runs the same suite on every push against the latest WordPress with SQLite and the MCP Adapter. See CONTRIBUTING.md for a full local setup.

Limitations (v0.1)

• Search Console data is imported, not fetched: upload the CSV or let an agent push rows from a Search Console connector. A direct Google connection is on the roadmap.

• Click depth is modeled, not crawled: content links, menus (classic and block navigation), the blog index and category archives are followed; links printed only by theme templates or widgets are not.

• Cannibalization uses titles and focus keywords, not query-level data.

• Claude Code first. claude.ai custom connectors need OAuth, which WordPress Application Passwords don't provide; OAuth support is on the roadmap.

• Tested end-to-end on the demo site; performance on very large sites (10,000+ posts) has not been benchmarked yet. Scans are resumable and run in time-boxed batches.

Roadmap

• OAuth so SiteGraph works as a claude.ai / Claude Desktop connector

• Direct Search Console connection with scheduled re-imports and automatic impact reports

• Query-level cannibalization, redirects and "merge pages" changesets

• WP-CLI commands and background scans for large sites

• WooCommerce product and category pages

Repository layout

sitegraph-seo-agent/   WordPress plugin (abilities, MCP server, admin screens)
claude-plugin/         Claude Code plugin: skills + MCP connection (userConfig)
.claude-plugin/        Marketplace manifest (/plugin marketplace add am333ni7y/sitegraph-seo-agent)
demo/                  Demo site seed, Search Console sample, sample changesets
tests/                 Integration suite, test installer, php -S router
docs/screenshots/      Images used in this README
PRIVACY.md             Privacy policy (also linked from the Claude plugin)

The earlier Node.js wordpress-mcp server (generic post CRUD over WP-CLI/REST) is preserved in the git history before this release.

License

MIT © Amin Zahed