@littlebearapps/wp-navigator-mcp

v2.8.3

Published

a day ago

MCP server for AI-assisted WordPress management via Claude Code and other MCP clients

0High
0Medium
0Low

nathanschram

mcp model-context-protocol wordpress claude ai cms wp-navigator anthropic

WP Navigator MCP

AI-powered WordPress management via Claude Code 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.

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

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

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

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

2. Create Application Password

In WordPress Admin: Users → Your Profile → Application Passwords

Enter a name (e.g., "WP Navigator MCP")
Click "Add New Application Password"
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

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"
      }
    }
  }
}

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.

Invocation Patterns

# Recommended: Use the package directly (runs CLI if command provided)
npx @littlebearapps/wp-navigator-mcp init
npx @littlebearapps/wp-navigator-mcp --version
npx @littlebearapps/wp-navigator-mcp tools

# Alternative: Use the wpnav binary (installed globally or via npx -p)
npx -p @littlebearapps/wp-navigator-mcp wpnav init
npm install -g @littlebearapps/wp-navigator-mcp && wpnav init

Note: The package is scoped, so npx wpnav@version won't work. Use the full package name @littlebearapps/wp-navigator-mcp.

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
npx wpnav init --repair          # Fix broken configuration (v2.4.0+)

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 tools --format markdown  # Generate documentation
npx wpnav configure   # Set up credentials interactively
npx wpnav validate    # Validate config and manifest
npx wpnav doctor      # Run system diagnostics
npx wpnav cleanup     # Remove onboarding helper files

Multi-Platform Support (v2.3.0)

# Generate MCP configuration for your platform
npx wpnav mcp-config --claude    # Claude Code (.mcp.json)
npx wpnav mcp-config --codex     # OpenAI Codex (config.toml)
npx wpnav mcp-config --gemini    # Google Gemini CLI (settings.json)

# Export config as environment variables
npx wpnav export-env             # Shell format
npx wpnav export-env --format docker  # Dockerfile
npx wpnav export-env --format github  # GitHub Actions

Zero-Friction Setup (v2.7.0)

Magic Link — Connect instantly from WordPress admin:

# Copy link from WordPress → WP Navigator → Connect AI
npx wpnav connect wpnav://connect?site=example.com&token=abc123...

Context for non-MCP agents — Generate context for ChatGPT and other web AI:

npx wpnav context                # Markdown format
npx wpnav context --compact      # Reduced tokens

Role management — AI personas with focused tool access:

npx wpnav role list              # List available roles
npx wpnav role show developer    # Show role details
npx wpnav role set content-editor # Set active role

AI Guidance Features (v2.6.0)

Roles — AI personas with focused tool access and behavior guidance:

npx wpnav call wpnav_list_roles           # List available roles
npx wpnav call wpnav_load_role --slug content-editor  # Load a role

Built-in roles: content-editor, developer, seo-specialist, site-admin

Cookbooks — Plugin-specific AI guidance for Gutenberg, Elementor, and more:

npx wpnav call wpnav_list_cookbooks       # List available cookbooks
npx wpnav call wpnav_load_cookbook --slug gutenberg  # Load cookbook

MCP Resources — Context delivery for AI assistants:

wpnav://tools/overview — Categorized tool list
wpnav://site/context — Current site information
wpnav://roles/{slug} — Role definitions
wpnav://cookbooks/{slug} — Plugin guidance

Site Understanding Tools (v2.8.0)

Site Health — WordPress Site Health integration:

npx wpnav call wpnav_site_health                      # Full health report
npx wpnav call wpnav_site_health --categories security,performance

Site Statistics & Settings — Comprehensive site metrics:

npx wpnav call wpnav_site_statistics     # Posts, users, comments counts
npx wpnav call wpnav_site_settings       # General settings overview

Discovery — Explore WordPress capabilities:

npx wpnav call wpnav_list_rest_routes    # All REST API endpoints
npx wpnav call wpnav_list_shortcodes     # Registered shortcodes
npx wpnav call wpnav_list_block_patterns # Available block patterns
npx wpnav call wpnav_list_block_templates # FSE block templates

Options Management — Plugin options (safe by default):

npx wpnav call wpnav_get_option --option woocommerce_currency
npx wpnav call wpnav_set_option --option yoast_seo_title --value "My Site"

Security: wpnav_set_option only allows plugin-detected prefixes (e.g., woocommerce_*, yoast_*). Core WordPress options are blocked.

Maintenance — Site maintenance operations:

npx wpnav call wpnav_flush_rewrite       # Flush rewrite rules
npx wpnav call wpnav_maintenance_mode --enable true   # Enable maintenance
npx wpnav call wpnav_maintenance_mode --enable false  # Disable maintenance

AI-Friendly Suggestions — Context-aware guidance:

npx wpnav suggest                        # Get contextual suggestions
npx wpnav suggest --limit 3              # Limit suggestions

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.

Project Structure

When you initialize a WP Navigator project with npx wpnav init, the following structure is created:

my-wp-project/
├── wpnavigator.jsonc       # Site manifest (your intent)
├── wpnav.config.json       # Connection configuration
├── .gitignore              # Ignores credentials and snapshots
├── snapshots/              # Site state snapshots
│   ├── site_index.json     # Full site structure
│   └── pages/              # Individual page snapshots
├── roles/                  # Custom AI role definitions
├── cookbooks/              # Custom plugin cookbooks (override bundled)
├── docs/                   # Project documentation
└── sample-prompts/         # Ready-to-use AI prompts
    ├── self-test.txt
    ├── add-page.txt
    └── content-audit.txt

Directory Purposes

| Directory | Purpose | Git Status | |-----------|---------|------------| | snapshots/ | Read-only state from WordPress | Ignore (regeneratable) | | roles/ | Custom AI behavior definitions | Commit | | cookbooks/ | Plugin-specific AI guidance | Commit | | docs/ | Project documentation | Commit | | sample-prompts/ | Reusable AI prompts | Commit |

Recommended .gitignore

# Credentials (NEVER commit)
wpnav.config.json

# Snapshots (regenerate with wpnav snapshot)
snapshots/

Available Tools

93 tools available through the Dynamic Toolsets architecture.

MCP-Exposed Tools (5)

These tools are directly exposed to AI via MCP:

| Tool | Purpose | |------|---------| | wpnav_introspect | Check connection, policy, plugin status | | wpnav_search_tools | Find tools by query or category | | wpnav_describe_tools | Load full schemas for specific tools | | wpnav_execute | Execute any tool dynamically | | wpnav_context | Get context for non-MCP AI agents |

Discoverable Tools (93)

All other tools are discovered via wpnav_search_tools and executed via wpnav_execute:

| Category | Tools | Examples | |----------|-------|----------| | Core | 7 | wpnav_get_site_overview, wpnav_search, wpnav_list_post_types | | 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 | | Batch | 3 | wpnav_batch_get, wpnav_batch_update, wpnav_batch_delete | | Cookbook | 3 | wpnav_list_cookbooks, wpnav_load_cookbook | | Roles | 2 | wpnav_list_roles, wpnav_load_role | | Options | 2 | wpnav_get_option, wpnav_set_option | | Settings | 2 | wpnav_site_settings, wpnav_site_statistics | | Health | 1 | wpnav_site_health | | Discovery | 4 | wpnav_list_rest_routes, wpnav_list_shortcodes, wpnav_list_block_patterns | | Maintenance | 2 | wpnav_flush_rewrite, wpnav_maintenance_mode |

CLI Tool Discovery

List and search tools via CLI:

npx wpnav tools                          # List all tools
npx wpnav tools --category gutenberg     # Filter by category
npx wpnav tools --search "create post"   # Search by query

Architecture

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

Dynamic Toolsets (v2.7.0)

WP Navigator uses a Dynamic Toolsets architecture for token efficiency:

| Approach | Token Usage | Tools Exposed | |----------|-------------|---------------| | v2.6 (legacy) | ~19,500 tokens | 75 individual tools | | v2.7+ (dynamic) | ~500 tokens | 5 meta-tools (93 discoverable) |

How it works:

Search — AI uses wpnav_search_tools to find relevant tools by natural language query
Describe — AI uses wpnav_describe_tools to load full schemas for tools it wants to use
Execute — AI uses wpnav_execute to run tools with validated arguments

Meta-tools exposed to AI:

| Tool | Purpose | |------|---------| | wpnav_introspect | Check connection, policy, plugin status | | wpnav_search_tools | Find tools by query or category | | wpnav_describe_tools | Get full schemas for specific tools | | wpnav_execute | Execute any tool dynamically | | wpnav_context | Get context for non-MCP AI agents |

Example flow:

AI: "I need to create a blog post"

1. wpnav_search_tools(query: "create blog post")
   → Returns: wpnav_create_post, wpnav_create_post_with_blocks

2. wpnav_describe_tools(tools: ["wpnav_create_post_with_blocks"])
   → Returns: Full schema with parameters

3. wpnav_execute(tool: "wpnav_create_post_with_blocks", arguments: {...})
   → Creates the post

Local Development (v2.4.0+)

WP Navigator supports local development environments like LocalWP, Docker, and MAMP.

Environment Variable Credentials

Keep credentials out of config files using $VAR syntax:

{
  "WP_BASE_URL": "http://localhost:8080",
  "WP_REST_API": "http://localhost:8080/wp-json",
  "WPNAV_BASE": "http://localhost:8080/wp-json/wpnav/v1",
  "WPNAV_INTROSPECT": "http://localhost:8080/wp-json/wpnav/v1/introspect",
  "WP_APP_USER": "$WP_APP_USER",
  "WP_APP_PASS": "$WP_APP_PASS"
}

Then set environment variables:

export WP_APP_USER="admin"
export WP_APP_PASS="xxxx xxxx xxxx xxxx"

HTTP for Localhost

For local development without HTTPS:

ALLOW_INSECURE_HTTP=1 npx wpnav status

Or in your MCP config:

{
  "env": {
    "ALLOW_INSECURE_HTTP": "1"
  }
}

Repair Mode

Fix broken or outdated configuration:

npx wpnav init --repair

This validates existing files and regenerates any that are missing or invalid.

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 | | WP_APP_USER | - | WordPress username (for env-based credentials) | | WP_APP_PASS | - | WordPress application password (for env-based credentials) |

Compatibility

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

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

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

Quick Troubleshooting

| Issue | Solution | |-------|----------| | "Command starts MCP server" | Update to v2.8.0+, use npx @littlebearapps/wp-navigator-mcp@latest | | "Config not found" | Config auto-discovers from parent dirs; use --config for explicit path | | "401 Unauthorized" | Regenerate Application Password in WordPress Admin → Users → Profile | | "WRITES_DISABLED" | Set WPNAV_ENABLE_WRITES=1 environment variable | | "Plugin not found" (404) | Ensure WP Navigator plugin is installed and activated | | SSL errors | Use ALLOW_INSECURE_HTTP=1 for localhost development |

Full diagnostics:

npx wpnav doctor          # Run system health checks
npx wpnav doctor --json   # JSON output for debugging

See Troubleshooting Guide for detailed solutions.

Documentation

Getting Started:

Getting Started — Quick setup in 5 minutes
MCP Setup — Configure Claude Code, Codex, Gemini CLI

Reference:

CLI Reference — Complete command documentation
Dynamic Toolsets — Token-efficient tool discovery architecture
Security — Security model and best practices

Guides:

Best Practices — Token optimization, security, and workflow tips
AI Agent Guide — Dynamic Toolsets workflow for AI agents
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