WP Navigator MCP

AI-powered WordPress management via Claude Code, Claude Desktop, and MCP-compatible clients.

Manage posts, pages, media, plugins, themes, and Gutenberg blocks through natural language — all with safe-by-default writes and full rollback support.

<!-- TODO: Add demo GIF when available -->

---

Coming Soon — January 2025

The WP Navigator WordPress plugin is not yet available. This MCP server requires the plugin to be installed on your WordPress site.

Register your interest at wpnav.ai →

---

Who Is This For?

WordPress Developer	Content Manager
"I want AI to help build and maintain sites"	"I want to manage content with natural language"
You build WordPress sites and want AI assistance for development tasks.	You manage content and want faster, more intuitive workflows.
Key features: Gutenberg block editing, plugin management, theme switching, bulk operations	Key features: Post/page creation, media uploads, safe publishing, content rollback

---

What WP Navigator MCP Does

Content Management

• Create and edit posts/pages with Gutenberg blocks
• Upload media from URLs (sideload images automatically)
• Manage comments, categories, and tags
• Full revision history with rollback support

Site Management

• Install, activate, and manage plugins
• Switch and customize themes
• View and manage WordPress users

Safety & Rollback

• Safe by default — Writes disabled until explicitly enabled
• Full revision history — Rollback any content change
• Policy-based access — WordPress plugin enforces granular permissions
• HTTPS enforced — Secure connections for non-localhost

---

Quick Start

1. Install WP Navigator Plugin

<details> <summary><strong>Free Version (WordPress.org)</strong></summary>

Search for "WP Navigator" in WordPress Plugins → Add New, or:

1. Download from WordPress.org
2. Upload to /wp-content/plugins/
3. Activate the plugin

</details>

<details> <summary><strong>Pro Version</strong></summary>

1. Purchase at wpnav.ai/pro
2. Download the plugin ZIP
3. Upload via WordPress Admin → Plugins → Add New → Upload
4. Activate and enter your license key

</details>

2. Create Application Password

In WordPress Admin: Users → Your Profile → Application Passwords

1. Enter a name (e.g., "WP Navigator MCP")
2. Click "Add New Application Password"
3. Copy the password immediately (it won't be shown again)

3. Create Configuration File

Create wpnav.config.json in your project directory:

{
  "WP_BASE_URL": "https://your-site.com",
  "WP_REST_API": "https://your-site.com/wp-json",
  "WPNAV_BASE": "https://your-site.com/wp-json/wpnav/v1",
  "WPNAV_INTROSPECT": "https://your-site.com/wp-json/wpnav/v1/introspect",
  "WP_APP_USER": "your-username",
  "WP_APP_PASS": "xxxx xxxx xxxx xxxx xxxx xxxx"
}

4. Configure Your MCP Client

<details> <summary><strong>Claude Code</strong></summary>

Add to your project's .mcp.json:

{
  "mcpServers": {
    "wpnav": {
      "command": "npx",
      "args": ["-y", "@littlebearapps/wp-navigator-mcp", "./wpnav.config.json"],
      "env": {
        "WPNAV_ENABLE_WRITES": "1"
      }
    }
  }
}

</details>

<details> <summary><strong>Claude Desktop</strong></summary>

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "wpnav": {
      "command": "npx",
      "args": ["-y", "@littlebearapps/wp-navigator-mcp", "/full/path/to/wpnav.config.json"],
      "env": {
        "WPNAV_ENABLE_WRITES": "1"
      }
    }
  }
}

Restart Claude Desktop after editing.

</details>

Note: WPNAV_ENABLE_WRITES=1 enables create/update/delete operations. Without it, only read operations work (safe by default).

5. Verify Connection

In Claude, try:

"Use wpnav_introspect to check the WordPress connection"

---

CLI Mode

WP Navigator MCP also works as a standalone CLI for scripts and web-based AI agents.

Initialize a Project

npx wpnav init                   # Interactive wizard (guided mode)
npx wpnav init --mode scaffold   # Quick setup without prompts
npx wpnav init --mode ai-handoff # Create AI-ready handoff document

Creates project structure with wpnavigator.jsonc manifest and sample-prompts/ folder containing ready-to-use AI prompts (self-test, add-page, content-audit, etc.).

Direct Tool Invocation

# List posts
npx wpnav call wpnav_list_posts --limit 5

# Get site overview
npx wpnav call wpnav_get_site_overview

# Preview a change without executing
npx wpnav call wpnav_update_post --id 1 --title "New Title" --dry-run

Other Commands

npx wpnav status      # Check WordPress connection and plugin edition
npx wpnav tools       # List available tools
npx wpnav configure   # Set up credentials interactively
npx wpnav validate    # Validate config and manifest
npx wpnav validate --json --snapshots  # Machine-readable output with snapshot validation
npx wpnav doctor      # Run system diagnostics
npx wpnav cleanup     # Remove onboarding helper files

Snapshot & Sync Workflow

npx wpnav snapshot site       # Capture full site index
npx wpnav snapshot page about # Capture single page
npx wpnav diff                # Compare manifest vs WordPress
npx wpnav sync --dry-run      # Preview changes
npx wpnav sync                # Apply manifest to WordPress
npx wpnav rollback <id>       # Restore from pre-sync snapshot

See CLI Reference for complete documentation.

---

Available Tools

65+ tools organized by category:

Category	Tools	Examples
Core	5	wpnav_introspect, wpnav_get_site_overview
Posts	7	wpnav_list_posts, wpnav_create_post_with_blocks
Pages	6	wpnav_list_pages, wpnav_snapshot_page
Media	4	wpnav_upload_media_from_url
Plugins	7	wpnav_list_plugins, wpnav_activate_plugin
Themes	7	wpnav_list_themes, wpnav_activate_theme
Gutenberg	7	wpnav_gutenberg_insert_block
Users	5	wpnav_list_users, wpnav_get_user
Comments	5	wpnav_list_comments, wpnav_create_comment
Taxonomy	12	wpnav_list_categories, wpnav_create_tag

List all tools:

npx wpnav tools
npx wpnav tools --category gutenberg

---

Architecture

┌─────────────────────┐     MCP Protocol     ┌────────────────────┐
│   Claude Code /     │ ◄──────────────────► │  WP Navigator MCP  │
│   Claude Desktop    │                       │   (npm package)    │
└─────────────────────┘                       └─────────┬──────────┘
                                                        │ REST API
                                                        ▼
                                              ┌────────────────────┐
                                              │     WordPress      │
                                              │   + WP Navigator   │
                                              │      Plugin        │
                                              └────────────────────┘

---

Environment Variables

Variable	Default	Description
WPNAV_ENABLE_WRITES	0	Enable write operations (create/update/delete)
ALLOW_INSECURE_HTTP	0	Allow HTTP for localhost development
WPNAV_TOOL_TIMEOUT_MS	600000	Per-tool timeout (10 minutes)
WPNAV_MAX_RESPONSE_KB	64	Maximum response size before truncation

---

Compatibility

WP Navigator MCP	WP Navigator Free	WP Navigator Pro	Node.js
v1.0.x	v1.0+	v1.0+	18+

MCP Clients: Claude Desktop, Claude Code, Gemini CLI, any MCP-compatible client

Platforms: macOS (Apple Silicon & Intel), Linux (x64), Windows (via WSL)

---

Documentation

• CLI Reference — Complete command documentation
• Security — Security model and best practices
• Troubleshooting — Common issues and solutions
• FAQ — Frequently asked questions
• Contributing — How to contribute

---

Support & Community

• Bug Reports: Open an Issue
• Feature Requests: Start a Discussion
• Questions: Ask in Discussions
• Documentation: wpnav.ai/docs

---

Related Projects

Project	Description
WP Navigator Free	WordPress plugin (Free)
WP Navigator Pro	WordPress plugin (Premium)

---

License

MIT — see LICENSE for details.

---

Made with care by Little Bear Apps

Issues · Discussions · Changelog