wordpress-mcp-server

KuljeetSinghXDA/wordpress-mcp-server

3.2

If you are the rightful owner of wordpress-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The WordPress MCP Server is an AI-powered content management system designed to enhance WordPress sites with advanced content creation, optimization, and management capabilities.

Tools
18
Resources
0
Prompts
0

WordPress MCP Server

AI-Powered WordPress Content Management System
A Model Context Protocol (MCP) server that provides AI-powered content creation, optimization, and management for WordPress sites using 6 specialized AI agents and 18 comprehensive tools.

TypeScript Node.js WordPress Docker License: MIT

🚀 Features

6 Specialized AI Agents

  1. Research Agent - Finds authoritative sources, creates citations
  2. Content Agent - Generates original, engaging content with citations
  3. Humanizer Agent - Reduces AI patterns, ensures originality (<30 AI score)
  4. SEO/GEO/AEO Agent - Meta optimization, internal linking, GEO/AEO optimization
  5. UI/UX Agent - Layout design, spacing, visual hierarchy
  6. Nexter Agent - Generates Nexter blocks with custom CSS

18 MCP Tools

Primary Tools (4)
  • create_post - Create AI-powered blog posts
  • create_page - Create AI-powered pages
  • update_post - Update existing posts with AI refinement
  • update_page - Update existing pages with AI refinement
Refinement Tools (7)
  • refine_content - Refine text content in specific blocks
  • refine_layout - Improve visual layout and spacing
  • refine_block - Regenerate specific Nexter blocks
  • add_to_section - Add content to existing sections
  • remove_from_section - Remove content from sections
  • reorder_blocks - Reorder blocks for better flow
  • fix_visual_issue - Fix spacing, alignment, responsiveness
Retrieval Tools (4)
  • get_post - Retrieve post by ID
  • search_posts - Search posts by keywords
  • list_posts - List recent posts
  • get_post_structure - Get post structure as block tree
Utility Tools (3)
  • validate_request - Pre-validate create/update requests
  • compare_revisions - Compare post versions
  • rollback_to_revision - Rollback to previous version

Advanced Features

  • ✅ CSV Keywords Prompt - Load keywords from CSV for targeted content
  • ✅ Citations & Research - Automatic source finding and citation integration
  • ✅ Internal Linking - Smart internal link suggestions and integration
  • ✅ Originality Focus - AI humanizer reduces AI detection (<30 score)
  • ✅ GEO Optimization - Generative Engine Optimization (AI search engines)
  • ✅ AEO Optimization - Answer Engine Optimization (featured snippets)
  • ✅ Nexter Blocks - 90+ advanced WordPress blocks with custom CSS
  • ✅ Block Processing - Non-destructive editing with validation
  • ✅ Multi-Provider AI - Support for OpenAI, Anthropic, Google, Groq via LiteLLM
  • ✅ Google Search Integration - Via g-search-mcp service
  • ✅ Docker Deployment - Containerized services with health checks

📋 Table of Contents

🔧 Prerequisites

  • Node.js 18+ and npm
  • Docker and Docker Compose (for containerized deployment)
  • WordPress site with:
    • REST API enabled
    • Application Password for authentication
    • Nexter blocks plugin (optional, for advanced blocks)
  • AI Provider API Keys (at least one):
    • OpenAI API key (OPENAI_API_KEY)
    • Anthropic API key (ANTHROPIC_API_KEY)
    • Google API key (GOOGLE_API_KEY)
    • Groq API key (GROQ_API_KEY)

📦 Installation

Option 1: Docker (Recommended)

# Clone the repository
git clone https://github.com/KuljeetSinghXDA/wordpress-mcp-server.git
cd wordpress-mcp-server

# Copy environment file
cp .env.example .env

# Edit .env with your credentials
nano .env

# Start services
docker-compose up -d

Option 2: Local Development

# Clone the repository
git clone https://github.com/KuljeetSinghXDA/wordpress-mcp-server.git
cd wordpress-mcp-server

# Install dependencies
npm install

# Copy environment file
cp .env.example .env

# Edit .env with your credentials
nano .env

# Build TypeScript
npm run build

# Start the MCP server
npm start

⚙️ Configuration

1. WordPress Setup

Create an Application Password in WordPress:

  1. Go to Users → Profile
  2. Scroll to Application Passwords
  3. Enter a name (e.g., "MCP Server")
  4. Click Add New Application Password
  5. Copy the generated password (format: xxxx xxxx xxxx xxxx xxxx xxxx)

2. Environment Variables

Edit .env file:

# WordPress Configuration
WP_SITE_URL=https://yoursite.com
WP_USERNAME=admin
WP_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx

# AI Models (User Configurable)
LITELLM_MODEL_CONTENT=gpt-4
LITELLM_MODEL_RESEARCH=gpt-4
LITELLM_MODEL_HUMANIZER=gpt-4
LITELLM_MODEL_SEO=gpt-4
LITELLM_MODEL_UIUX=gpt-3.5-turbo
LITELLM_MODEL_NEXTER=gpt-4

# AI Provider Keys (Set at least one)
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxx
GOOGLE_API_KEY=xxxxxxxxxxxxxxxxxxxxx
GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxxxxxxx

3. Feature Flags

Customize features in .env:

ENABLE_RESEARCH_AGENT=true
ENABLE_WEB_SEARCH=true
ENABLE_CITATIONS=true
ENABLE_AI_HUMANIZER=true
ENABLE_GEO_OPTIMIZATION=true
ENABLE_AEO_OPTIMIZATION=true
ENABLE_NEXTER_CHECK=true

🎯 Usage

Creating a Post

{
  "tool": "create_post",
  "arguments": {
    "title": "10 Best AI Tools for Content Creation",
    "topic": "AI tools for content writers and marketers",
    "tone": "professional",
    "word_count": 1500,
    "keywords": ["AI tools", "content creation", "copywriting"],
    "enable_research": true,
    "enable_citations": true,
    "enable_internal_links": true,
    "status": "draft"
  }
}

Updating a Post

{
  "tool": "update_post",
  "arguments": {
    "post_id": 123,
    "instructions": "Add a section about GPT-4 and improve SEO",
    "preserve_existing": true
  }
}

Refining Content

{
  "tool": "refine_content",
  "arguments": {
    "post_id": 123,
    "block_id": "tpgb-abc123",
    "instructions": "Make this paragraph more engaging and add statistics"
  }
}

CSV Keywords Example

{
  "tool": "create_post",
  "arguments": {
    "title": "Complete Guide to SEO",
    "csv_keywords": "keyword,search_volume\nSEO tools,10000\nbacklink checker,5000\nkeyword research,8000",
    "topic": "SEO tools and techniques",
    "enable_research": true
  }
}

📚 API Documentation

Tool: create_post

Create an AI-powered blog post with research, citations, and optimization.

Parameters:

{
  title: string;              // Post title
  topic: string;              // Content topic/brief
  tone?: string;              // professional|casual|friendly|formal
  word_count?: number;        // Target word count (default: 1200)
  keywords?: string[];        // Target keywords
  csv_keywords?: string;      // CSV format: "keyword,volume"
  enable_research?: boolean;  // Enable research agent (default: true)
  enable_citations?: boolean; // Add citations (default: true)
  enable_internal_links?: boolean; // Add internal links (default: true)
  enable_humanizer?: boolean; // Run humanizer (default: true)
  status?: string;            // publish|draft|pending (default: draft)
  categories?: number[];      // Category IDs
  tags?: number[];            // Tag IDs
}

Response:

{
  success: boolean;
  post_id: number;
  post_url: string;
  ai_score?: number;          // AI detection score (lower is better)
  citations_count?: number;
  internal_links_count?: number;
  blocks_count: number;
  seo_score?: {
    title_optimized: boolean;
    description_optimized: boolean;
    geo_optimized: boolean;
    aeo_optimized: boolean;
  };
}

Tool: update_post

Update existing post with AI refinement.

Parameters:

{
  post_id: number;            // Post ID to update
  instructions: string;       // Update instructions
  preserve_existing?: boolean; // Keep existing blocks (default: true)
  enable_humanizer?: boolean; // Run humanizer (default: true)
  status?: string;            // Update status (optional)
}

Tool: refine_content

Refine specific text content in blocks.

Parameters:

{
  post_id: number;            // Post ID
  block_id: string;           // Block ID (e.g., "tpgb-abc123")
  instructions: string;       // Refinement instructions
}

Tool: get_post_structure

Get post structure as block tree.

Parameters:

{
  post_id: number;            // Post ID
}

Response:

{
  post_id: number;
  title: string;
  blocks: Array<{
    block_id: string;
    block_name: string;
    block_type: string;
    attributes: Record<string, any>;
    inner_blocks: Array<...>;
  }>;
  blocks_count: number;
  nexter_blocks_count: number;
}

🏗️ Architecture

System Overview

┌─────────────────────────────────────────────────────────────┐
│                     MCP Client (Claude)                     │
└───────────────────────────┬─────────────────────────────────┘
                            │ MCP Protocol
┌───────────────────────────▼─────────────────────────────────┐
│                  WordPress MCP Server                       │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  18 MCP Tools (Primary, Refinement, Retrieval)      │  │
│  └────────────────────┬─────────────────────────────────┘  │
│  ┌────────────────────▼─────────────────────────────────┐  │
│  │  6 AI Agents (Research, Content, Humanizer, etc.)   │  │
│  └────────────────────┬─────────────────────────────────┘  │
│  ┌────────────────────▼─────────────────────────────────┐  │
│  │  Block Engine (Parser, Serializer, Validator)       │  │
│  └────────────────────┬─────────────────────────────────┘  │
└───────────────────────┼─────────────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        │               │               │
   ┌────▼────┐    ┌────▼────┐    ┌────▼────┐
   │WordPress│    │LiteLLM  │    │ Google  │
   │REST API │    │(AI)     │    │ Search  │
   └─────────┘    └─────────┘    └─────────┘

Component Details

1. Block Processing Engine

  • Parser (src/blocks/parser.ts)

    • Uses WordPress block-serialization-spec-parser
    • Parses block comments to structured objects
    • Helper functions: extractBlockIds, findBlockById, countBlocks

  • Serializer (src/blocks/serializer.ts)

    • Converts parsed blocks back to WordPress format
    • Block manipulation: createBlock, insertBlockAt, removeBlockById
    • Non-destructive editing support

  • Validator (src/blocks/validator.ts)

    • Validates block structure against WordPress/Nexter rules
    • Nexter blocks MUST have block_id (pattern: tpgb-[a-z0-9]+)
    • Validates JSON-serializability, nested blocks, duplicate IDs
2. WordPress REST API Client
  • Client (src/wordpress/client.ts)
    • Basic auth with Application Passwords
    • Methods: createPost, updatePost, getPost, getPosts, searchPosts
    • Retry logic with exponential backoff
    • Error handling for 401, 403, 404, 429, 500 status codes
3. LiteLLM Integration
  • Client (src/ai/litellm.ts)
    • Unified interface to 100+ AI providers
    • Configurable models per agent type
    • Temperature and max_tokens per agent
    • Environment-based API key selection
4. AI Agents
  • ResearchAgent - Finds authoritative sources, creates citations
  • ContentAgent - Generates original content with citations
  • HumanizerAgent - Reduces AI patterns (<30 AI score)
  • SEOAgent - Meta optimization, GEO/AEO, internal linking
  • UIUXAgent - Layout design, spacing, visual hierarchy
  • NexterAgent - Generates Nexter blocks with custom CSS

🚢 Deployment

Docker Compose

The docker-compose.yml includes:

  1. wordpress-mcp-server - Main MCP server
  2. g-search-mcp - Google Search integration
# Start services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

# Restart services
docker-compose restart

Health Checks

Both services include health checks:

  • wordpress-mcp-server: HTTP check on port 3000
  • g-search-mcp: HTTP check on port 3001

Environment Variables in Docker

The .env file is automatically loaded by Docker Compose.

💻 Development

Project Structure

wordpress-mcp-server/
├── src/
│   ├── blocks/              # Block processing engine
│   │   ├── parser.ts        # WordPress block parser
│   │   ├── serializer.ts    # Block serializer
│   │   └── validator.ts     # Block validator
│   ├── wordpress/           # WordPress REST API
│   │   └── client.ts        # WordPress client
│   ├── ai/                  # AI integration
│   │   ├── litellm.ts       # LiteLLM client
│   │   └── agents.ts        # 6 AI agents
│   ├── tools/               # MCP tools
│   │   └── mcp-tools.ts     # 18 MCP tools
│   └── index.ts             # Entry point
├── docker-compose.yml       # Docker services
├── .env.example             # Environment template
├── package.json             # Dependencies
├── tsconfig.json            # TypeScript config
└── README.md                # This file

Build Commands

# Install dependencies
npm install

# Build TypeScript
npm run build

# Start development server
npm run dev

# Start production server
npm start

# Run tests
npm test

# Lint code
npm run lint

Adding New Tools

  1. Define tool schema in src/tools/mcp-tools.ts
  2. Implement tool handler function
  3. Register tool in MCP server
  4. Update documentation

Adding New Agents

  1. Create agent class in src/ai/agents.ts
  2. Configure LiteLLM model in .env
  3. Integrate agent in tool workflow
  4. Update documentation

🔍 Troubleshooting

WordPress Authentication Failed (401)

Solution:

  1. Verify Application Password format (with spaces)
  2. Check username is correct
  3. Ensure REST API is enabled
  4. Test credentials: curl -u username:password https://yoursite.com/wp-json/wp/v2/posts

AI Provider Error

Solution:

  1. Verify API key is correct
  2. Check API key has sufficient credits
  3. Ensure correct model name (e.g., gpt-4 not gpt4)
  4. Test with different provider

Block Validation Failed

Solution:

  1. Check Nexter blocks have block_id attribute
  2. Verify block_id format: tpgb-[a-z0-9]+
  3. Ensure no duplicate block IDs
  4. Validate JSON serializability

Docker Container Won't Start

Solution:

  1. Check .env file exists and has correct format
  2. Verify port 3000 and 3001 are available
  3. Check Docker logs: docker-compose logs
  4. Rebuild containers: docker-compose up --build

High AI Detection Score

Solution:

  1. Enable humanizer: ENABLE_AI_HUMANIZER=true
  2. Increase temperature: TEMPERATURE_HUMANIZER=0.9
  3. Use different model for humanizer
  4. Run humanizer multiple times

🤝 Contributing

Contributions are welcome! Please follow these steps:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Development Guidelines

  • Follow TypeScript best practices
  • Add tests for new features
  • Update documentation
  • Use meaningful commit messages
  • Keep code DRY and modular

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

📞 Support

🗺️ Roadmap

  • Add support for custom post types
  • Implement image generation and optimization
  • Add multilingual support
  • Create web dashboard for monitoring
  • Add analytics and reporting
  • Implement batch processing
  • Add support for WooCommerce
  • Create WordPress plugin version

Made with ❤️ by KuljeetSinghXDA

⭐ Star this repo if you find it helpful!