WP Navigator MCP

# WP Navigator MCP [](https://www.npmjs.com/package/@littlebearapps/wp-navigator-mcp) [](https://www.npmjs.com/package/@littlebearapps/wp-navigator-mcp) [](https://github.com/littlebearapps/wp-navigator-mcp/actions/workflows/ci.yml) [](https://codecov.io/gh/littlebearapps/wp-navigator-mcp) [](https://opensource.org/licenses/MIT) **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. <!-- 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 →](https://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](https://wordpress.org/plugins/wp-navigator/) 2. Upload to `/wp-content/plugins/` 3. Activate the plugin </details> <details> <summary><strong>Pro Version</strong></summary> 1. Purchase at [wpnav.ai/pro](https://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: ```json { "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`: ```json { "mcpServers": { "wpnav": { "command": "npx", "args": ["-y", "@littlebearapps/wp-navigator-mcp", "./wpnav.config.json"], "env": { "WPNAV_ENABLE_WRITES": "1" } } } } ``` </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. ### Invocation Patterns ```bash # 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 ```bash 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 ```bash # 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 ```bash 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) ```bash # 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: ```bash # 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: ```bash npx wpnav context # Markdown format npx wpnav context --compact # Reduced tokens ``` **Role management** — AI personas with focused tool access: ```bash 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: ```bash 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: ```bash 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 ### Snapshot & Sync Workflow ```bash 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](docs/cli-reference.md) 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 ```gitignore # Credentials (NEVER commit) wpnav.config.json # Snapshots (regenerate with wpnav snapshot) snapshots/ ``` --- ## Available Tools **75+ tools** available through the [Dynamic Toolsets](#dynamic-toolsets-v270) 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 (75+) 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` | ### CLI Tool Discovery List and search tools via CLI: ```bash 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 | **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:** | 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: ```json { "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: ```bash export WP_APP_USER="admin" export WP_APP_PASS="xxxx xxxx xxxx xxxx" ``` ### HTTP for Localhost For local development without HTTPS: ```bash ALLOW_INSECURE_HTTP=1 npx wpnav status ``` Or in your MCP config: ```json { "env": { "ALLOW_INSECURE_HTTP": "1" } } ``` ### Repair Mode Fix broken or outdated configuration: ```bash 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) --- ## Documentation - **[CLI Reference](docs/cli-reference.md)** — Complete command documentation - **[Security](docs/security.md)** — Security model and best practices - **[Troubleshooting](docs/troubleshooting.md)** — Common issues and solutions - **[FAQ](docs/faq.md)** — Frequently asked questions - **[Contributing](docs/contributing.md)** — How to contribute --- ## Support & Community - **Bug Reports**: [Open an Issue](https://github.com/littlebearapps/wp-navigator-mcp/issues/new?template=bug_report.yml) - **Feature Requests**: [Start a Discussion](https://github.com/littlebearapps/wp-navigator-mcp/discussions/new?category=ideas) - **Questions**: [Ask in Discussions](https://github.com/littlebearapps/wp-navigator-mcp/discussions/new?category=q-a) - **Documentation**: [wpnav.ai/docs](https://wpnav.ai/docs) --- ## Related Projects | Project | Description | |---------|-------------| | [WP Navigator Free](https://wordpress.org/plugins/wp-navigator/) | WordPress plugin (Free) | | [WP Navigator Pro](https://wpnav.ai/pro) | WordPress plugin (Premium) | --- ## License MIT — see [LICENSE](LICENSE) for details. --- **Made with care by [Little Bear Apps](https://littlebearapps.com)** [Issues](https://github.com/littlebearapps/wp-navigator-mcp/issues) · [Discussions](https://github.com/littlebearapps/wp-navigator-mcp/discussions) · [Changelog](CHANGELOG.md)