littlebearapps/wp-navigator-mcp

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?

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

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

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

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:

Discoverable Tools (93)

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

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:

How it works:

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

Meta-tools exposed to AI:

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

Compatibility

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

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

Quick Troubleshooting

Full diagnostics:

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

See for detailed solutions.

Documentation

Getting Started:

• — Quick setup in 5 minutes
• — Configure Claude Code, Codex, Gemini CLI

Reference:

• — Complete command documentation
• — Token-efficient tool discovery architecture
• — Security model and best practices

Guides:

• — Token optimization, security, and workflow tips
• — Dynamic Toolsets workflow for AI agents
• — Common issues and solutions
• — Frequently asked questions
• — 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

License

MIT — see for details.

Made with care by Little Bear Apps

Issues · Discussions ·