What can you do with this server?

WP Navigator MCP enables AI-powered WordPress management through natural language commands with a token-efficient architecture and comprehensive safety controls. **Token-Efficient Architecture:** Uses only 5 meta-tools (~500 tokens) instead of exposing all 93+ tools (~19,500 tokens): * `wpnav_introspect` - Check connection, policy, and plugin status * `wpnav_search_tools` - Discover tools via natural language queries or categories * `wpnav_describe_tools` - Load detailed schemas only for needed tools * `wpnav_execute` - Execute any discovered tool with validated arguments * `wpnav_context` - Get compact site context for AI initialization **Core Capabilities:** * **Content Management**: Create/edit posts/pages with Gutenberg blocks, manage comments/categories/tags, full revision history and rollback * **Media Operations**: Upload and manage media files, automatic sideloading from URLs * **Site Management**: Install/activate/manage plugins and themes, view/manage users, configure site options and settings * **Site Health & Diagnostics**: Health reports, statistics, performance metrics, maintenance mode control, rewrite rule flushing * **Discovery Tools**: List REST API routes, shortcodes, block patterns, and block templates * **Batch Operations**: Bulk create, update, and delete operations on multiple items **Safety & Workflow Features:** * Safe-by-default writes (disabled until explicitly enabled) * Policy-based access control with HTTPS enforcement for non-localhost * Full revision history and rollback support * Snapshot creation, diff comparison, and sync operations * Repair mode for broken configurations **AI Guidance:** * Built-in roles (content-editor, developer, SEO-specialist, site-admin) for focused workflows * Plugin-specific cookbooks (Gutenberg, Elementor) for tailored assistance **CLI & Compatibility:** * Standalone CLI for scripts/web AI agents with zero-friction setup via magic links * Project initialization with manifest/snapshots * Works with Claude Code, Gemini CLI, and any MCP-compatible clients * Cross-platform support (macOS, Linux, Windows via WSL) * Environment variable credentials with HTTP support for localhost

Which integrations are available for this server?

Provides tools for working with WordPress [Gutenberg](/mcp/servers/integrations/gutenberg) blocks, including inserting, editing, and managing block-based content within WordPress posts and pages. Enables AI-powered [WordPress](/mcp/servers/integrations/wordpress) management including creating and editing posts/pages with Gutenberg blocks, uploading media, managing plugins and themes, handling comments and taxonomies, and performing bulk operations with full revision history and rollback support.

WP Navigator MCP enables AI-powered WordPress management through natural language commands with a token-efficient architecture and comprehensive safety controls.

Token-Efficient Architecture: Uses only 5 meta-tools (~500 tokens) instead of exposing all 93+ tools (~19,500 tokens):

wpnav_introspect - Check connection, policy, and plugin status
wpnav_search_tools - Discover tools via natural language queries or categories
wpnav_describe_tools - Load detailed schemas only for needed tools
wpnav_execute - Execute any discovered tool with validated arguments
wpnav_context - Get compact site context for AI initialization

Core Capabilities:

Content Management: Create/edit posts/pages with Gutenberg blocks, manage comments/categories/tags, full revision history and rollback
Media Operations: Upload and manage media files, automatic sideloading from URLs
Site Management: Install/activate/manage plugins and themes, view/manage users, configure site options and settings
Site Health & Diagnostics: Health reports, statistics, performance metrics, maintenance mode control, rewrite rule flushing
Discovery Tools: List REST API routes, shortcodes, block patterns, and block templates
Batch Operations: Bulk create, update, and delete operations on multiple items

Safety & Workflow Features:

Safe-by-default writes (disabled until explicitly enabled)
Policy-based access control with HTTPS enforcement for non-localhost
Full revision history and rollback support
Snapshot creation, diff comparison, and sync operations
Repair mode for broken configurations

AI Guidance:

Built-in roles (content-editor, developer, SEO-specialist, site-admin) for focused workflows
Plugin-specific cookbooks (Gutenberg, Elementor) for tailored assistance

CLI & Compatibility:

Standalone CLI for scripts/web AI agents with zero-friction setup via magic links
Project initialization with manifest/snapshots
Works with Claude Code, Gemini CLI, and any MCP-compatible clients
Cross-platform support (macOS, Linux, Windows via WSL)
Environment variable credentials with HTTP support for localhost

WP Navigator MCP

npm version npm downloads codecov License: 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.

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

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

License

MIT — see LICENSE for details.

Made with care by

Issues · Discussions · Changelog

Install Server

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

Resources

Need Help?

Report Issue

Related Servers