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.
Made by AMEEEN ZED · Part of WP Needs — WordPress plugins, themes and support
Ameeen SEO 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.
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.
Ameeen SEO 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:
- Judgment — a site-wide link graph and page scores, joined with search demand, turned into a ranked action plan.
- 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.
| You do this today with… | Ameeen SEO… |
|---|---|
| A crawler (e.g. Screaming Frog) to find orphan pages, click depth and broken internal links | Reads the graph from the database in seconds, no crawl, always current |
| Spreadsheets joining a crawl with a Search Console export | Joins them for you and ranks pages by issues × demand |
| An internal-linking plugin's keyword suggestions | Finds sentences that already mention the topic and turns them into ready operations |
| Editing posts one by one in wp-admin | Applies a reviewed changeset in one step — and undoes it in one step |
| "What did the AI change last Tuesday?" | Every change has a history, a diff, and Undo/Redo buttons |
It does not replace keyword research or backlink tools (Ahrefs, Semrush): it works on what you control on your own site.
Because it sees your internal links, your content, your search data and can act, an agent with Ameeen SEO 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?"
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]
- 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. - 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. - Score — each page starts at 100 and loses points per issue (see Scoring).
- 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. - Change — the agent proposes a changeset; you approve; it is applied atomically, recorded, and reversible.
On the demo site in this repository (39 pages, three months of Search Console data):
You: Audit my site with Ameeen SEO 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:
- 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.
- 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.
- 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.
The suggestions are existing sentences on related pages. Select them and propose a changeset without leaving wp-admin.
Rings show click depth from the home page; colors show page scores; pages outside the dashed ring cannot be reached by clicking.
- 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)
Copy the ameeen-seo-agent folder to wp-content/plugins/ (or zip it and upload it under Plugins → Add New → Upload), then activate it. Open Ameeen SEO in wp-admin and click Scan site.
Search Console → Performance → Search results → pick a date range → Export → Download CSV. Upload Pages.csv from the zip on the Ameeen SEO Overview screen.
Ameeen SEO never creates credentials. Create an Application Password yourself under Users → Profile → Application Passwords, then open Ameeen SEO → Connect an agent. It shows the MCP URL and how to build the access token, the Base64 of username:application password, with one-line PowerShell and bash commands. You can revoke the Application Password in your profile at any time.
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/ameeen-seo-agent
/plugin install ameeen-seo@ameeen
Claude Code asks for the MCP URL and the access token you built in step 3 when you enable it; the token goes to your system's secure credential store. Then ask: "Audit my site with Ameeen SEO and tell me the five changes that would help most."
Prefer to connect without the plugin? Run claude mcp add --transport http ameeen-seo <MCP URL> --header "Authorization: Basic <token>" with the MCP URL and token from step 3.
| Skill | Use it for |
|---|---|
seo-audit |
Health check and a short prioritized plan with evidence |
fix-internal-links |
Orphans, deep pages, striking-distance pages — proposes links, applies after approval |
rewrite-snippets |
Low-CTR pages and missing descriptions — offers options, applies the chosen ones |
review-changes |
"What did you change?", undo, redo, and measuring impact |
Other MCP clients (Cursor, VS Code, Claude Desktop through a proxy) can use the same endpoint; the MCP Adapter docs cover client configuration.
All tools are WordPress abilities in the ameeen-seo/ namespace, exposed on a dedicated MCP server at /wp-json/ameeen-seo/v1/mcp (tool names use -, e.g. ameeen-seo-scan-site). They are also discoverable through the MCP Adapter's default server.
| Tool | Changes content? | What it does |
|---|---|---|
scan-site |
No | Builds the link graph and scores pages; resumable for large sites |
get-site-overview |
No | Health summary, issue counts, five weakest pages |
list-weak-pages |
No | Pages weakest first, filterable by issue and post type |
get-page-report |
No | One page: issues and fixes, inbound/outbound/broken links, search data, SEO fields |
get-action-plan |
No | Ranked tasks with impact, effort, automation level and a suggested prompt |
suggest-internal-links |
No | Existing sentences that could link to a page, as ready operations |
import-search-data |
No (stores search data) | Page-level Search Console rows |
propose-changeset |
No | Validates operations against live content and stores a reviewable proposal |
apply-changeset |
Yes (destructive hint) | Applies a proposal atomically; refuses if content changed since |
undo-changeset |
Yes (destructive hint) | Restores every field exactly; refuses to overwrite newer edits |
redo-changeset |
Yes (destructive hint) | Re-applies an undone changeset |
discard-changeset |
No | Drops a proposal |
list-changesets / get-changeset |
No | History, diffs, available actions, impact before vs now |
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 Ameeen SEO prints the title tag and meta description itself.
Every page starts at 100. Issues subtract points; the most damaging are listed first.
| Issue | Points | Impact | Needs Search Console |
|---|---|---|---|
| Orphan page (no internal links in) | −30 | High | |
| Not reachable by clicking from home | −15 | High | |
| Broken internal links | −10 | High | |
| Low CTR for its position (≥ 500 impressions) | −12 | High | ✓ |
| Striking distance (position 8–20) | −6 | High | ✓ |
| Thin content (< 300 words; pages < 150) | −20 | Medium | |
| No search impressions | −15 | Medium | ✓ |
| Buried deep (4+ clicks) | −12 | Medium | |
| Only one internal link in | −10 | Medium | |
| Competes with another page for the same topic | −10 | Medium | |
| Short content (< 600 words) | −8 | Low | |
| Not updated in 18+ months | −8 | Low | |
| No internal links out | −6 | Low | |
| Missing meta description | −6 | Low | |
| Title shorter than 20 or longer than 65 characters | −4 | Low |
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.
- Real user, real permissions. The agent authenticates as your WordPress user with an Application Password. Tools require
edit_others_posts(Editors and Admins; filterameeen_seo_capability), and every write also checksedit_postfor 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;
forceexists 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: Ameeen SEO has no server of its own, sends no telemetry, and the author receives no data.
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 APICI 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.
- 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.
- OAuth so Ameeen SEO 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
ameeen-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/ameeen-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.
Ameeen SEO Agent is made by AMEEEN ZED — SEO specialist and WordPress developer. Website design and SEO services: aminzahed.ir.
It is part of WP Needs, a marketplace for WordPress plugins, themes and technical support.