🤘 Claudeus WordPress MCP 🎸

"Unleash the Power of AI in Your WordPress Realm!" 🖤

🏢 The Team Behind the Magic

SimHop IT & Media AB - Where Innovation Meets Metal 🤘

Based in the heart of Sweden, SimHop IT & Media AB is the powerhouse behind Claudeus WordPress MCP. We're not your typical tech company - we're a fusion of technical excellence and creative innovation, orchestrating digital solutions that rock!

🎸 The Maestros

Amadeus Samiel H. (CTO/Lead Solutions Architect)

• MSc in Computer Science
• 20+ years crafting digital excellence
• Instructor at LIU and other institutes
• The technical virtuoso behind Claudeus WP MCP
• Specializations: System Architecture, Creative Development, Technical Education

Simon Malki (CEO)

• 20+ years orchestrating business success
• Expert in strategic planning and market dynamics
• The business mastermind driving SimHop's vision
• Specializations: Business Strategy, Market Analysis, Technical Operations

🏗️ Our Dual-Power Structure

Stockholm HQ (Business & Strategy) 📍 Krögers Promenad 11, 191 37 Sollentuna

• Strategic Operations
• Business Development
• Market Strategy
• Client Relations

Norrköping Division (Technical Innovation) 📍 Klingsbergsgatan 13, 603 54 Norrköping

• Development & Architecture
• Technical Innovation
• R&D Operations

🤘 Why We Made It Free

Claudeus WordPress MCP was born from our passion for both heavy metal and heavy-duty WordPress development. We believe in the power of open source and the spirit of the developer community. Just as metal music brings people together, we wanted to create a tool that would unite WordPress developers and make their lives easier.

By open-sourcing Claudeus WP MCP, we're giving back to the community that has given us so much. It's our way of saying "thank you" and helping others achieve WordPress enlightenment! 🎸

🔥 Our Philosophy

1. Technical Excellence: Like a perfectly executed guitar solo
2. Creative Innovation: Breaking boundaries, creating new possibilities
3. Community First: Sharing the power with everyone
4. Continuous Evolution: Always pushing the boundaries

"We believe in empowering developers with tools that rock as hard as they do!" - Amadeus & Simon

🌟 Unleash Your WordPress Superpowers!

Are you tired of the endless grind of WordPress management? Drowning in content creation, SEO optimization, and site maintenance? Get ready to experience something that will blow your mind! 🤯

🎸 Meet Your New WordPress Superpower 🖤

Claudeus WordPress MCP isn't just another WordPress tool – it's your personal WordPress wizard, powered by cutting-edge AI and crafted with the precision of a metal guitarist's sweep picking! This isn't just automation; it's liberation! ❤️

⚡ What Makes It Epic?

• Content Creation on Steroids: Generate engaging, SEO-optimized blog posts ✓ READY
• Bulk Operations at Light Speed: Manage hundreds of posts across multiple sites ✓ READY
• AI-Powered SEO Magic: Let AI analyze and optimize your content ✓ READY
• WooCommerce Mastery: Handle products, orders, and sales ✓ READY
• Multi-Site Orchestra: Conduct multiple WordPress sites ✓ READY

💥 Why Developers Are Going Crazy

Traditional WordPress → 😫 Hours of manual work
Claudeus WP MCP   → 🚀 INSTANT RESULTS!

Content Creation: 4 hours → 30 minutes
SEO Optimization: 2 hours → 15 minutes
Bulk Updates: 8 hours → 45 minutes

🎯 Imagine Being Able To...

• Create weeks of content in minutes ✓
• Analyze and optimize your entire site's SEO instantly ✓
• Manage multiple client sites with supernatural efficiency ✓
• Handle WooCommerce operations at lightning speed ✓
• All while your competition is still logging into WordPress! ✓

🔮 The Future of WordPress is Here

This isn't just a tool – it's your ticket to WordPress enlightenment. Whether you're a solo developer, agency owner, or WordPress enthusiast, Claudeus WordPress MCP gives you superpowers that will make your competition's jaws drop!

"I've seen the future of WordPress management, and it's absolutely metal! 🤘❤️" - Every Developer After Using Claudeus WP MCP

Ready to transform your WordPress workflow from a garage band to a stadium-filling metal symphony? Let's rock! 🎸

📖 Quick Start Guide

Using with Claude Desktop

If you're using Claude Desktop, you only need to:

1. Configure Claude Desktop integration (see "Claude Desktop Integration" section)
2. Create and configure your wp-sites.json file
3. Rock on! 🤘

Full Installation (for development)

# Required Software
Node.js ≥ 22.0.0
TypeScript ≥ 5.0.0
PNPM
WordPress site with REST API

2. Installation

# Clone the repository
git clone https://github.com/deus-h/claudeus-wp-mcp

# Install dependencies
pnpm install

# Build the project
pnpm build

# Configure Claude Desktop
cp claude_desktop_config.json.example claude_desktop_config.json
# Edit claude_desktop_config.json with your settings

3. Configuration

# Copy example configs
cp .env.example .env
cp wp-sites.json.example wp-sites.json

# Edit .env and wp-sites.json with your settings

Configuring wp-sites.json

The wp-sites.json file is used to configure your WordPress sites for integration. Below is an example structure:

{
  "site-alias": {
    "URL": "https://your-wordpress-site.com",
    "USER": "username",
    "PASS": "application-password",
    "authType": "basic"  // or "jwt"
  }
}

• URL: The URL of your WordPress site.
• USER: The username for authentication.
• PASS: The application password for secure access.
• authType: The authentication type, either "basic" or "jwt".

Obtaining the Application Password

1. Log in to your WordPress Admin Dashboard.
2. Navigate to Users > Profile.
3. Scroll down to the Application Passwords section.
4. Enter a name for the application and click "Add New".
5. Copy the generated password and use it in your wp-sites.json file.

Ensure that your wp-sites.json file is kept secure and not shared publicly.

Multi-Site Configuration

The wp-sites.json file allows you to manage multiple WordPress sites seamlessly. Here's how you can set it up:

Example Structure

{
  "default_test": {
        "URL": "https://test.yourdomain.se",
        "USER": "admin",
        "PASS": "Hn5K pL8x Wm2j Vt9q Bc4y Rs7D",
        "authType": "basic"
    },
  "live": {
    "URL": "https://our-live-site.se",
    "USER": "deus",
    "PASS": "Kj9P mN2x vR4h Zt8L wQ5y Bc3M",
    "authType": "basic"
  },
  "test": {
    "URL": "https://our-test-site.se",
    "USER": "deus",
    "PASS": "Yw7H fT6n Jm5k Vd9x Pg4q Ls2B", 
    "authType": "basic"
  },
  "client1_live": {
    "URL": "https://client1-live-site.se",
    "USER": "deus",
    "PASS": "Xc8D bN4v Ht6m Rk2p Zj9w Qf5L",
    "authType": "basic"
  },
  "client1_test": {
    "URL": "https://client1-test-site.se",
    "USER": "deus",
    "PASS": "Gm7B sW3x Yn5h Kt9q Vf4c Pd2L",
    "authType": "basic"
  }
}

Logic and Usage

• Site Aliases: Each site is identified by a unique alias (e.g., live, test, client1_live). This allows you to easily switch between different environments or client sites.
• URL: The base URL for each WordPress site.
• USER: The username used for authentication.
• PASS: The application password for secure access.
• authType: Defines the authentication method, either basic or jwt.

How to Use

1. Define Multiple Sites: Add as many site configurations as needed, each with a unique alias.
2. Switch Between Sites: Use the alias to select the desired site for operations.
3. Secure Access: Ensure that each site has a valid application password and secure authentication method.
4. Environment Management: Easily manage different environments (e.g., live, test) for each client.

This setup allows you to efficiently manage multiple WordPress sites from a single configuration file, streamlining your workflow and enhancing productivity.

4. Rock and Roll with MCP Inspector! 🎸

# Start the MCP Inspector UI
pnpm inspector

# This will:
# 1. Build the project
# 2. Launch the Inspector UI
# 3. Open your browser at http://localhost:5173

Exploring with Inspector UI

1. Connect to Server

   • Click "Connect" in the top-right corner
   • Select "Local Server" for development

2. Available Features

   • 🎸 Prompts: Test AI content generation
   • 🛠 Tools: Manage WordPress operations
   • 📦 Resources: Browse WordPress sites
   • 🔍 Inspector: Debug server communication

3. Testing Prompts

   • Select "Prompts" tab
   • Try create-blog-post with your ideas
   • Analyze SEO with analyze-post-seo
   • Bulk update with bulk-update-posts

4. Managing Resources

   • Browse connected WordPress sites
   • View site details and capabilities
   • Test API endpoints directly

5. Using Tools

   • Create and update content
   • Manage media files
   • Run bulk operations

🤘 Pro Tip: Use the Inspector tab to see real-time communication between the UI and server!

🎮 Claude Desktop Integration

Configuration Location

The Claude Desktop configuration file can be found at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

⚠️ IMPORTANT: If you already have other MCP servers configured in Claude Desktop, DO NOT directly copy our example file as it will overwrite your existing configuration! Instead:

1. For existing Claude Desktop users:

   • Open your existing config through Claude Desktop:
     • Click on the Claude menu
     • Select "Settings..."
     • Click on "Developer" in the lefthand bar
     • Click on "Edit Config"
   • OR open your config file directly in a text editor
   • Add our Claudeus WordPress MCP server configuration to your existing mcpServers object

2. For new Claude Desktop users: You can copy our example config file:

   # For macOS
   cp /Users/amadeus/code/claudeus/servers/claudeus-wp-mcp/claude_desktop_config.json.example ~/Library/Application\ Support/Claude/claude_desktop_config.json
   
   # For Windows (in PowerShell)
   Copy-Item claude_desktop_config.json.example $env:APPDATA\Claude\claude_desktop_config.json

🎸 Pro Tip: Our example config file comes pre-configured with the optimal settings - just update the path to your wp-sites.json!

Usage with Claude Desktop

Add this to your claude_desktop_config.json:

NPX Setup

{
  "mcpServers": {
    "claudeus-wp-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "claudeus-wp-mcp"
      ],
      "env": {
        "WP_SITES_PATH": "/absolute/path/to/your/wp-sites.json"
      }
    }
  }
}

Docker Setup 🐳

{
  "mcpServers": {
    "claudeus-wp-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network=host",
        "--mount", "type=bind,src=/absolute/path/to/your/wp-sites.json,dst=/app/wp-sites.json",
        "--mount", "type=bind,src=/absolute/path/to/your/.env,dst=/app/.env",
        "mcp/wordpress",
        "--config", "/app/wp-sites.json"
      ]
    }
  }
}

🎸 Pro Tip: Make sure to replace /absolute/path/to/your/wp-sites.json with the actual path to your configuration file!

After Configuration

1. Restart Claude Desktop completely
2. Look for the hammer 🔨 icon in the bottom right corner of the input box
3. Click it to see available WordPress management tools
4. Start shredding! 🤘

Troubleshooting

If the server isn't showing up in Claude:

1. Verify your claude_desktop_config.json syntax
2. Ensure file paths are absolute and valid
3. Check Claude's logs at:
   • macOS: ~/Library/Logs/Claude
   • Windows: %APPDATA%\Claude\logs

🎯 What is This?

Claudeus WordPress MCP is your ultimate AI-powered WordPress management system. It's like having a metal band's precision and power, but for your WordPress sites!

💪 Core Features

1. Content Management

2. AI Capabilities

🛠 Technical Deep Dive

Architecture 🏗️

Welcome to the backstage of our metal symphony! Each component is like an instrument in our technical orchestra, working together to create the most epic WordPress management system ever! 🤘🖤

Directory Structure 🎸

src/
├── api/              # WordPress API integration layer
│   ├── client/       # WordPress REST API client
│   ├── endpoints/    # Endpoint definitions & handlers
│   └── types/        # WordPress API type definitions
│
├── mcp/              # MCP protocol implementation
│   ├── server.ts     # Core MCP server implementation
│   ├── transport/    # Transport layer handlers
│   ├── tools.ts      # Tool registration & management
│   └── types/        # MCP protocol type definitions
│
├── security/         # Security framework
│   ├── auth/         # Authentication handlers
│   ├── validation/   # Input validation
│   └── encryption/   # Data encryption utilities
│
├── tools/            # Tool implementations
│   ├── content/      # Content management tools
│   ├── media/        # Media handling tools
│   ├── shop/         # WooCommerce integration
│   └── system/       # System management tools
│
└── prompts/          # AI prompt templates
    ├── content/      # Content generation prompts
    ├── seo/          # SEO analysis prompts
    └── shop/         # E-commerce prompts

Core Components 🤘

Technical Amplification 🎸

Security Measures 🛡️

Performance Tuning 🚀

Error Categories & Handling 🎸

Design Principles Power Chord 🤘

🎸 Pro Tip: Like a well-tuned guitar, each component is precisely calibrated for maximum shredding capability! ❤️

🎸 The Power of MCP

Time Savings

Cost Efficiency

Claudeus Solution: All these capabilities for just $20/month with Claude Pro subscription

Total Monthly Savings: $3,480 (99.4% reduction) ❤️

🎸 Pro Tip: One Claude Pro subscription replaces multiple expensive services, turning your WordPress management from a costly orchestra into a lean, mean, Metal Machine! 🤘

⚡ With Great Power...

"With great power comes great responsibility" - Uncle Ben

The Claudeus WordPress MCP is a powerful tool that can:

• Save hundreds of hours of manual work
• Reduce operational costs by up to 85%
• Improve content quality and consistency
• Automate repetitive tasks

But remember:

1. Always review AI-generated content
2. Keep security best practices in mind
3. Monitor system usage and performance
4. Maintain backup strategies
5. Use the power responsibly! 🤘

⚠️ Issues and Considerations

Current Limitations and Workarounds

1. Claude Desktop Response Limits

• Issue: Claude Desktop's maximum response length can be reached frequently during complex operations
• Impact: Operations may be interrupted, requiring user intervention to continue
• Workaround:
  • Configure Claude Desktop to break tasks into smaller batches
  • In Claude Desktop Settings > Advanced:
    • Set "Maximum Response Length" to a lower value
    • Enable "Auto-split Responses"
  • Use the Inspector UI for large-scale operations

2. Experimental Capabilities Control

• Issue: The new capability control feature in wp-sites.json is experimental
• Status: Integrated but under testing
• Example Configuration:

{
    "capabilities": {
        "discovery": {
            "claudeus_wp_discover_endpoints": true
        },
        "posts": {
            "claudeus_wp_content__get_posts": true,
            "claudeus_wp_content__create_post": true,
            "claudeus_wp_content__update_post": true,
            "claudeus_wp_content__delete_post": false
        }
        // ... other capabilities
    }
}

• Considerations:
  • Use with caution in production environments
  • Test thoroughly in staging first
  • Consider contributing improvements (see Contributing section)
  • Default to basic configuration if unsure

3. Rate Limiting Considerations

• Issue: WordPress REST API has rate limits
• Impact: Bulk operations might be throttled
• Mitigation:
  • Use batch processing features
  • Implement appropriate delays between requests
  • Monitor API response headers for rate limit info

4. Memory Management

• Issue: Large operations can consume significant memory
• Impact: Potential performance degradation
• Best Practices:
  • Monitor system resources during large operations
  • Use pagination for large datasets
  • Implement cleanup routines

Future Improvements

We're actively working on:

1. Improved response handling in Claude Desktop
2. Stable release of capabilities control
3. Advanced rate limiting management
4. Memory optimization techniques

🎸 Pro Tip: Check our GitHub Issues for workarounds and best practices!

🎸 Support and Community ❤️

• GitHub Issues: Report bugs and request features
• Documentation: Full technical docs
• Examples: Sample implementations

🏗️ MCP Server Development Standards

MCP Protocol Compliance

Claudeus WordPress MCP adheres to the highest standards of MCP server development:

• ✅ Full MCP 2024-11-05 Spec Compliance

  • Proper capability declarations
  • Standard message format adherence
  • Correct transport handling (stdio/SSE)

• 🔄 Protocol Features Implementation

  capabilities: {
      prompts: {
          listChanged: true
      },
      tools: {
          listChanged: true
      },
      resources: {
          listChanged: true
      }
  }

• 🛡️ Security Standards

  • Strict input validation
  • Proper error handling
  • Secure authentication flows
  • Rate limiting implementation

Development Guidelines

Code Style

• ✓ TypeScript strict mode enabled
• ✓ ESLint configuration with recommended rules
• ✓ Prettier for consistent formatting
• ✓ JSDoc documentation for public APIs

Architecture Principles

src/
├── api/          # WordPress API integration
├── mcp/          # MCP protocol implementation
├── security/     # Security framework
├── tools/        # Tool implementations
└── prompts/      # AI prompt templates

Testing Requirements

• Unit tests for core functionality
• Integration tests for WordPress API
• End-to-end tests for MCP protocol
• Security vulnerability scanning

🧪 Testing Framework

Our testing framework is built with precision and reliability in mind, just like a well-tuned guitar! 🎸

Test Structure

• Unit Tests: Comprehensive testing of individual components
• Integration Tests: Ensuring components work together harmoniously
• JSON-RPC Protocol Testing: Validating server-client communication
• Custom Test Harness: Simulating real-world scenarios

Key Features

• Custom Matchers: Enhanced Jest matchers for JSON-RPC validation
• Test Transport Layer: Simulated transport for controlled testing
• Async Operation Support: Extended timeouts for complex operations
• Error Handling Tests: Comprehensive error scenario coverage

Running Tests

# Run all tests
pnpm test

# Run specific test suite
pnpm test:unit
pnpm test:integration

# Run with coverage
pnpm test:coverage

🤝 Contributing

Ready to join our band of WordPress warriors? Here's how to contribute:

1. ✓ Fork the repository
2. ✓ Create your feature branch (git checkout -b feature/AmazingFeature)
3. ✓ Write and run tests for your changes
   • Ensure all existing tests pass
   • Add new tests for your features
   • Maintain test coverage above 80%
4. ✓ Commit your changes (git commit -m '🎸 Add some AmazingFeature')
5. ✓ Push to the branch (git push origin feature/AmazingFeature)
6. ✓ Open a Pull Request

🔥 Pro Tip: Always run the test suite before submitting a PR!

🤘 License

MIT License - Rock on!

🛠 MCP Tools Reference

Tool Categories and Danger Levels

Danger Level Legend

• 🟢 Safe: Read-only operations, no data modification
• 🟡 Moderate: Creates or modifies content, but can be reverted
• 🔴 High: Destructive operations or system-wide changes

🤘 Pro Tip: Always test high-danger tools in a staging environment first!

⚠️ Warning: Use Data Manipulation Tools with Caution

Data manipulation tools in the Claudeus WordPress MCP are powerful and can significantly impact your WordPress sites. Here's what you need to know:

Potential Risks

• Data Loss: Incorrect use of tools can lead to unintended data deletion or modification.
• Site Downtime: Misconfigurations may cause site outages or performance issues.
• Security Vulnerabilities: Improper handling of sensitive data can expose your site to security risks.

Best Practices

1. ✓ SAFETY FIRST: Always create backups before operations
2. ✓ TEST SAFE: Use staging environment for new tools
3. ✓ VERIFY: Review changes before applying
4. ✓ SECURE: Restrict tool access to trusted users
5. ✓ MONITOR: Track tool usage and performance

Constructive Use

When used correctly, these tools can:

• ✓ Automate repetitive tasks
• ✓ Enhance site performance
• ✓ Improve content quality

"With great power comes great responsibility." Use these tools wisely to harness their full potential while minimizing risks.

Data Manipulation Tools

The following tools can create, update, or delete data on your WordPress site:

Content Management

• Posts:
  • claudeus_wp_content__create_post: Create new blog posts
  • claudeus_wp_content__update_post: Update existing posts
  • claudeus_wp_content__delete_post: Delete posts
• Pages:
  • claudeus_wp_content__create_page: Create new pages
  • claudeus_wp_content__update_page: Update existing pages
  • claudeus_wp_content__delete_page: Delete pages
• Blocks:
  • claudeus_wp_content__create_block: Create reusable blocks
  • claudeus_wp_content__update_block: Update existing blocks
  • claudeus_wp_content__delete_block: Delete blocks

Media Management

• claudeus_wp_media__upload: Upload new media files
• claudeus_wp_media__update: Update media metadata
• claudeus_wp_media__delete: Delete media items

Theme Customization

• claudeus_wp_theme__activate: Change active theme
• claudeus_wp_theme__update_customization: Modify theme settings
• claudeus_wp_theme__update_custom_css: Update custom CSS

Use these tools with caution to avoid unintended changes. Always:

1. Back up your data before making changes
2. Test in a staging environment first
3. Review changes before applying them
4. Monitor the results after application

"With great power comes great responsibility." Use these tools wisely to enhance your WordPress site while maintaining its integrity.

🚀 Coming Soon: Claudeus WordPress MCP Pro

If you think the Community Edition rocks hard, just wait until you see what's coming in the Pro version! 🤘

Pro Subscription Tiers 🎸

The Philosophy Behind Our Names: Our tier names follow the evolution of artificial intelligence itself - from basic neural networks to quantum computing, and finally to technological singularity. This progression represents not just increasing capabilities, but the transformation of WordPress management through advancing AI technology.

1. Claudeus WP Neural Server 🤘

The First Spark of AI-Powered WordPress Management

2. Claudeus WP Quantum Server 🎸

Breaking Classical Limitations with Quantum-Level Processing Everything in Neural Server, plus:

3. Claudeus WP Singularity Server ⚡

The Ultimate Evolution of WordPress Management Everything in Quantum Server, plus:

🔥 METAL ALERT: The Community Edition you're looking at is already a beast... but our Pro versions represent the evolution of WordPress management:

• Neural: The foundation of AI power
• Quantum: The leap beyond classical limitations
• Singularity: The ultimate transformation

Why Go Pro?

• Unlimited Power: No restrictions, no limits
• Priority Features: Get new features before anyone else
• Metal Support: Direct line to our development warriors
• Custom Solutions: Tailored to your specific needs
• Advanced AI: Specialized models for WordPress
• Pro UI Options: From Claude Desktop integration to full Universal Portal

🎸 Stay Tuned: Follow our GitHub repository to be the first to know when Pro launches and get early access to our epic interfaces!

🧙‍♂️ Words of Wisdom

npm is not a package manager, it's a repository of packages. If you want a dependable package manager, always use pnpm
— Amadeus Samiel H.

The Package Manager's Anthem

by Amadeus & Claudeus

In code's vast land,
npm stands, a host,
But pnpm's hand,
Manages most.

With iron might,
Dependencies align,
pnpm's light,
In code, it shines.

A true manager's call,
In the coder's hall,
pnpm reigns,
Above them all.

Made with 🤘❤️ by Amadeus Samiel H.