How We Built an MCP Server That Migrates WordPress Sites to Astro Automatically

We manage over a dozen WordPress sites. Some have 6,000+ posts, page builders stacked on top of each other, years of shortcodes, ACF fields, and content that has been touched by dozens of editors. When clients ask about moving to a modern static frontend, the conversation usually ends at it would take months.

So we built a tool that does it in hours.

WP Astro MCP is an open-source MCP server that migrates WordPress sites to Astro through conversational AI commands. We use it internally and we have open-sourced it for any agency or developer facing the same challenge.

The Problem Every Agency Faces

WordPress powers 40%+ of the web. It is the CMS most agencies know, most clients use, and most content teams are comfortable with. But performance expectations have changed. Clients want sub-second load times, perfect Core Web Vitals scores, and the security benefits of static sites.

Astro delivers all of that. It generates static HTML by default, ships zero JavaScript unless you explicitly need it, and supports every major UI framework like React, Vue, and Svelte when you do need interactivity. For content-heavy sites like blogs, documentation, marketing sites, and portfolios, Astro is the performance leader.

But migrating a real WordPress site to Astro is not a weekend project. Here is what the process actually involves:

Content is trapped in the WordPress database with page builder markup, shortcodes, and plugin-specific formatting
SEO metadata lives in Yoast or RankMath post meta fields that need extraction and mapping to frontmatter
Custom post types and ACF fields need structured YAML frontmatter with proper data types
Internal links throughout thousands of posts need remapping to new URL structures
Media URLs need domain swaps when WordPress moves from the primary domain to a subdomain
Redirects need to be generated for every old URL to maintain SEO equity
Navigation menus need extraction and rebuilding in Astro components
Content keeps changing while you migrate because editors do not stop publishing

For a site with 500 pages built in Elementor, a manual migration could take 2-3 developers 4-6 weeks. Multiply that across client sites and the cost becomes prohibitive. Most agencies turn down migration projects because the labor cost makes them unprofitable.

What Is MCP and Why It Matters for Agencies

The Model Context Protocol is an open standard developed by Anthropic that lets AI assistants connect to external tools and services. Think of it as a universal adapter. Build an MCP server once, and any AI client like Claude Code, Cursor, or Windsurf can use it.

For agencies, this means you can package complex workflows into tools that AI orchestrates through conversation. Instead of running scripts, configuring YAML files, and manually coordinating between APIs, you describe what you want in plain English and the AI handles the rest.

WP Astro MCP is our proof that this approach works for real-world, production-grade tasks. It is not a prototype or demo. It handles sites with thousands of posts, multiple page builders, and complex content structures.

55 Tools Across 8 Categories

WP Astro MCP connects to any WordPress site via the REST API and automates the entire migration through 55 specialized tools organized into 8 categories.

Site Management: 9 Tools

Register WordPress sites with credentials. The server auto-detects everything: WordPress version, REST API namespaces, SEO plugin (Yoast, RankMath, or AIOSEO), page builder (Elementor, WPBakery, Divi, Beaver Builder, Bricks, or Oxygen), ACF, WooCommerce, and all registered custom post types and taxonomies.

This auto-detection is critical. The migration pipeline automatically adjusts its behavior based on what the site uses. An Elementor site gets Elementor-specific cleanup. A Yoast site gets Yoast-specific SEO extraction. No manual configuration needed for common cases.

You can register multiple sites and switch between them by specifying a site ID. Each site has its own credentials, configuration, and export state. This is built for agencies managing multiple clients simultaneously.

Content Extraction: 13 Tools

Pull everything from WordPress with proper pagination and embedded relationships. Posts, pages, any custom post type, taxonomy terms with hierarchies, authors with avatars, navigation menus both classic and block-based, comments, widgets, media items, and site settings.

Two caching tools pre-fetch all taxonomy terms and authors into SQLite for fast lookups during conversion. On a site with 5,000 posts, this eliminates thousands of individual API calls that would otherwise slow down the conversion step significantly.

The content audit tool is especially valuable for scoping. It samples posts across the site and produces a complexity report: how many posts use Elementor, how many contain shortcodes, which specific shortcodes are in use and how often, what the conversion complexity distribution looks like. This data goes straight into your client proposal.

The 13-Step Conversion Pipeline

The core of the system. Every piece of WordPress content passes through 13 sequential transformation steps:

Sanitize with DOMPurify removes XSS vectors while preserving legitimate content
Resolve shortcodes with 20+ built-in handlers plus custom per-site rules and nested shortcode support over up to 10 passes
Clean page builders using Cheerio DOM manipulation to strip Elementor sections, WPBakery rows, Divi modules while keeping actual content
Process Gutenberg by removing block comments while preserving semantic content
Normalize HTML by decoding entities, removing empty paragraphs, cleaning inline styles
Convert to Markdown using Turndown with 12 WordPress-specific rules
Rewrite links by mapping internal WordPress URLs to Astro paths
Rewrite media with bulk domain swaps for go-live scenarios
Clean artifacts removing conversion leftovers and fixing double-encoded entities
Process embeds converting YouTube and Vimeo iframes to clean URLs
Handle galleries transforming WordPress galleries to structured image grids
Fix whitespace ensuring proper spacing around headings lists and code blocks
Validate flagging remaining HTML broken images and potential content loss

Each step exists because we hit a real problem on a real client site. The Elementor cleanup handles 15+ nested wrapper divs. The shortcode resolver handles custom product comparison shortcodes used in 200+ posts. Every step is a solution to a real-world migration problem we encountered.

How the Pipeline Handles Page Builders

Page builders are the biggest obstacle to clean content extraction. What looks like a simple two-column layout in the Elementor editor is actually a deeply nested DOM tree with dozens of wrapper elements, data attributes, custom CSS classes, and inline styles that serve no purpose outside the page builder context.

The pipeline recognizes markup patterns from six major page builders. For Elementor specifically, it identifies and strips elementor-section, elementor-column, elementor-widget-container, and all their nested wrapper divs while preserving the actual content inside widgets. A heading widget becomes a clean heading tag. A text editor widget becomes clean paragraphs. An image widget becomes a standalone image tag with proper alt text.

WPBakery uses a shortcode-based structure with vc_row, vc_column, and widget shortcodes. The pipeline resolves these shortcodes first, extracting content from each column, then cleans the remaining wrapper markup. Divi Builder uses a similar section-row-module pattern with its own et_pb prefixed classes.

The key insight is that page builders all follow the same fundamental pattern: containers wrapping containers wrapping containers wrapping actual content. The pipeline strips the containers and keeps the content. It is conceptually simple but the implementation handles hundreds of edge cases across different builder versions and configurations.

Shortcode Resolution in Depth

WordPress shortcodes are mini-programs embedded in content. Some are simple text wrappers. Others generate complex interactive elements. The pipeline ships with 20+ built-in handlers for common shortcodes: galleries, captions, audio, video, columns, tabs, accordions, buttons, and more.

For each shortcode the pipeline supports five resolution modes. Strip removes the shortcode tags but keeps the inner content, perfect for formatting shortcodes like columns. Keep content preserves everything inside for manual review. Remove deletes the shortcode and its content entirely, useful for deprecated plugins. Component converts the shortcode into an Astro component reference. HTML replaces the shortcode with static HTML markup.

Per-site custom rules let you configure handling for any shortcode. If a client site has a custom product-comparison shortcode used in 200 posts, you configure it once and every instance gets handled consistently.

The resolver handles nesting by running multiple passes, resolving inner shortcodes first before outer ones, up to 10 passes for deeply nested structures. This handles real-world patterns like tabs containing columns containing buttons, which we see regularly on client sites.

Output, Media, GitHub, Export Pipeline, and Content Sync

The remaining categories handle scaffolding complete Astro projects with layouts, content collections, and platform-specific deployment config. Redirect generation supports Netlify, Vercel, Cloudflare Pages, Apache, and Nginx. GitHub tools manage repository creation, commits, and pushes. The export pipeline is resumable with full state tracking in SQLite.

The content sync system is the most important differentiator. Seven sync tools detect new posts, updated content, changed images, modified SEO metadata, slug changes, and deletions. Automation configs generate ready-to-use GitHub Actions workflows, Vercel webhooks, or Netlify functions. The Astro site stays current automatically without anyone touching it.

Our Complete Agency Workflow

Phase 1: Discovery (30 minutes)

Register the client site. Auto-detection identifies WordPress version, plugins, page builder, and custom post types. Run analysis for content counts. Run a content audit for complexity distribution. Extract navigation menus and site settings. In 30 minutes you have everything needed for the client proposal including a realistic complexity estimate.

Phase 2: Preview and Configure (1-2 hours)

Preview 10 converted posts to verify conversion quality across different content types. Configure custom shortcode handlers for client-specific shortcodes. Set output directory and deployment platform. Review the conversion issue report for any content that needs manual attention. The client can review sample pages before committing to the full export.

Phase 3: Export (2-4 hours)

Cache all taxonomy terms and authors for fast lookups during conversion. Plan the export to see batch sizes and estimated completion time. Start the export in batches. Resume until complete. Retry any failures. Validate the output by checking that all expected files exist and match expected counts. For a 2,000-post site this takes about 2-3 hours with full state tracking so interruptions, network drops, and API rate limits are all handled gracefully.

Phase 4: Deploy

Generate redirects in whatever format the target platform needs. Initialize and push to a GitHub repository. Generate deployment configuration for Vercel, Netlify, or Cloudflare Pages. Connect the repo to the deployment platform for automatic builds on every push.

Phase 5: Ongoing Content Sync

Set up automated content sync via GitHub Actions (scheduled daily or hourly), Vercel webhooks (real-time on every publish), or Netlify functions. The system checks WordPress for new and updated posts, syncs changes to the Astro content directory, commits to git, and triggers a deployment. The editorial team keeps using WordPress exactly as they always have. The Astro frontend stays current. Everyone is happy.

Real Client Scenarios

Marketing Agency: 8 Client Blogs

A marketing agency manages 8 client WordPress blogs with 200-500 posts each. All 8 migrated to Astro frontends while keeping WordPress as the CMS. Each site registered with its own credentials and export configuration. One site per day. Total: 8 working days instead of the 8-12 weeks a manual migration would have taken.

E-Commerce Headless Frontend

WooCommerce store with Astro frontend for the product catalog. Only the product post type was exported with all WooCommerce metadata preserved in frontmatter including prices, stock status, variations, and product gallery images. Product pages load 3x faster while WooCommerce continues handling cart, checkout, and order management.

Enterprise Content: 5,000+ Posts

Media company with 5,000+ articles built over 7 years using WPBakery. JSON mode prevents out-of-memory errors during Astro builds that individual Markdown files would cause at this scale. Export ran over two days with automatic resume handling network interruptions. Real-time sync via Vercel webhooks keeps the Astro site current as the newsroom publishes new stories.

Multilingual Corporate Site

Corporate site with English and Spanish content managed through WPML. Language metadata preserved in taxonomy frontmatter. Both language versions migrated in one export run. Astro routing handles language-based URL prefixes. The content team continues managing translations in WordPress as before.

Portfolio with Complex ACF

Design agency portfolio with ACF repeater fields, relationship fields, and image galleries. All ACF data exports to clean YAML frontmatter. Images become objects with URL, alt text, width, and height. Relationships become references with WordPress ID, slug, and title. Repeaters become properly structured arrays. Zero manual data mapping required.

JSON Mode for Enterprise-Scale Sites

When a site has 500+ posts, individual Markdown files can overwhelm the Astro build process. Loading thousands of separate files into content collections consumes significant memory and can trigger out-of-memory errors during build.

JSON mode solves this by writing all posts in a collection to a single JSON file instead of individual Markdown files. The file contains an array of post objects with all frontmatter fields and converted content. Astro loads one file instead of thousands, dramatically reducing memory usage and build times.

The export config toggle is simple: set content_format to json instead of md. The entire pipeline still runs identically. The 13-step conversion still processes every post. The only difference is the output format. And the sync tools work seamlessly with JSON mode, updating individual entries within the JSON file rather than creating or deleting separate files.

For agencies handling enterprise clients with large content volumes, JSON mode is essential. We use it for any site over 500 posts as a standard practice.

Revenue Impact for Agencies

WordPress-to-Astro migration changes agency economics dramatically:

Delivery cost drops 80% from 4-6 weeks to 1-2 days of developer time per site
Charge $5,000-15,000 per migration based on site complexity, content volume, and custom requirements
Recurring revenue $500-1,500/month per site for content sync setup, maintenance, and ongoing support
Scale without hiring because the same tool handles every migration regardless of page builder or plugin stack
Competitive advantage since most agencies cannot offer fast and affordable WordPress-to-Astro migration
Upsell opportunities for custom Astro components, design refinement, and performance optimization after migration
Client retention because the ongoing sync service creates a long-term relationship beyond the initial migration project

One client migration at $8,000 plus $1,000/month sync service generates $20,000 in first-year revenue. Multiply across 10 clients and you have a $200,000 service line that barely existed before. The tooling cost is zero because WP Astro MCP is open-source.

Technical Architecture Overview

For technical teams evaluating the codebase: TypeScript with strict mode throughout and Zod schemas for input validation on every tool. The WordPress REST Client uses connection pooling with configurable max sockets, token-bucket rate limiting that auto-halves on 429 responses, and exponential backoff retries for server errors. SQLite with WAL mode provides concurrent read access across 8 tables for full state management including export jobs, per-post tracking, cached terms, cached authors, URL maps, shortcode rules, audit logs, and sync history.

Content transformation uses Cheerio for DOM manipulation during page builder cleanup, isomorphic DOMPurify for sanitization, Turndown with 12 custom rules for HTML-to-Markdown conversion, and a custom shortcode parser with multi-pass nested resolution. GitHub operations use Octokit for API calls and simple-git for local repository management.

The codebase follows a clear separation pattern: tools define interfaces and input schemas, handlers implement business logic, services encapsulate domain knowledge like WordPress API interaction and content transformation, and managers handle persistent state. Extending the system with new tools or modifying existing behavior is straightforward because each concern is isolated.

The router pattern deserves special mention. Instead of exposing all 55 tool definitions to the AI client, which would waste thousands of tokens on tool schemas, three meta-tools provide progressive discovery. The AI asks for help to list categories, describes a specific tool to get its schema, then runs it with the right parameters. This pattern is reusable for any MCP server with more than 10-15 tools.

Why We Open-Sourced It

We believe the WordPress ecosystem benefits when good tools are accessible. WP Astro MCP represents months of engineering effort solving real migration problems across dozens of client sites. The 13-step conversion pipeline handles edge cases that took us weeks to discover and fix. By open-sourcing it under the MIT license we enable other agencies to use it directly for client work, learn from the architecture for their own MCP servers, contribute improvements back to the project, and build profitable migration practices without the upfront development cost.

The WordPress-to-static-site migration market is growing. As more clients demand better performance, agencies need tools that make migration practical and profitable. We would rather grow the market than try to own it. Use it, modify it, build a business around it.

Getting Started

Requirements: Node.js 18+, WordPress 4.7+ with REST API enabled, and an application password for authentication.

git clone https://github.com/vapvarun/wp-astro-mcp.git
cd wp-astro-mcp
npm install & npm run build

Add the server to your Claude Code MCP configuration and start migrating. The complete wiki covers every tool, use case, configuration option, and real-world scenario in detail.

If you are an agency dealing with WordPress migrations, this tool fundamentally changes how you scope, price, and deliver those projects. The WordPress-to-Astro pipeline is the most profitable migration path available today, and WP Astro MCP makes it accessible to any agency willing to invest a day in learning the workflow.

Check it out: github.com/vapvarun/wp-astro-mcp

Magazine