A production-ready Model Context Protocol (MCP) server for cleaning malware from WordPress sites via SSH and WP-CLI. Designed for agencies and developers managing multiple WordPress installations.

Author: Varun Dubey Company: Wbcom Designs Version: 2.0.0

IMPORTANT SAFETY NOTICE

This tool performs irreversible operations on live WordPress sites including file deletion, database modification, password resets, and core file replacement. Always create a full backup before using any cleanup tool. The authors are not liable for data loss. See the Tool Risk Matrix below.

Hosting companies and agencies: See the Wiki for setup guides, daily scan automation, and the hosting company playbook.

• Before You Start
• Tool Risk Matrix
• Features
• Requirements
• Installation
• Configuration
• Quick Start
• Available Tools
• Usage Examples
• Cleanup Workflow
• Security Considerations
• Troubleshooting
• Contributing
• License
• Credits

Before using any cleanup or hardening tools on a live WordPress site:

1. Create a full server backup (files + database). Use your hosting provider's backup tool or:

   wp_backup_database("site-name")
   

   A database backup alone is not sufficient — back up the entire wp-content/ directory as well.

2. Test on staging first if possible. Clone the infected site to a staging environment and run cleanup there before touching production.

3. Keep an SSH session open to monitor the server during cleanup. Watch for errors or unexpected behavior.

4. Note current admin passwords before running wp_reset_passwords. After reset, the old passwords are gone permanently.

5. Destructive tools require confirm=True. Tools like wp_reinstall_core, wp_reset_passwords, wp_complete_cleanup, etc. will show a preview manifest when called without confirm=True. Review the manifest before confirming.

All tools are classified into three risk tiers:

These tools only read data. No files or database records are modified.

These tools make changes that can be undone or automatically create backups.

These tools permanently delete files, reset credentials, or overwrite data. Always create a backup first. Tools marked with confirm will show a preview manifest when called without confirm=True.

• Add and manage 20+ WordPress sites from a single interface
• Persistent configuration storage
• Batch operations across all sites
• Status tracking and reporting

• Core File Verification - Compare against official WordPress checksums
• Plugin Integrity Check - Verify plugins against WordPress.org
• MU-Plugins Detection - Scan must-use plugins for backdoors
• Uploads Security - Find PHP files that shouldn't exist
• Deep Pattern Matching - Detect obfuscated code and known signatures
• Database Injection Scan - Find malicious content in posts/options
• Recently Modified Files - Identify infection timeline

• List and audit administrator accounts
• Track user activity before deletion
• Find recently created suspicious users
• Safe user deletion with content reassignment

• Quarantine System - Move files instead of deleting (allows recovery)
• Automatic Backups - Database export before changes
• Core Reinstallation - Restore official WordPress files
• Plugin Reinstallation - Fresh install from repository
• Permission Fixes - Set secure file permissions

• Reset all admin passwords
• Regenerate security salts
• Disable admin file editing
• Add .htaccess security rules
• Update WordPress, plugins, and themes

• Detailed cleanup reports
• Action logging per site
• Export configurations
• Status summaries

• macOS 13+ (Ventura or later)
• Homebrew
• Claude Code CLI
• uv (Python package manager)

• SSH access (password or key-based)
• WP-CLI installed and in PATH
• WordPress 5.0+

Complete setup from scratch on a fresh Mac. Takes ~5 minutes.

• Homebrew installed
• Claude Code CLI installed
• uv installed (curl -LsSf https://astral.sh/uv/install.sh | sh)

# Python 3.12 (macOS system Python is too old for the mcp package)
brew install python@3.12

# sshpass (required for password-based SSH auth)
brew install sshpass

git clone https://github.com/vapvarun/wp-malware-cleanup-mcp.git ~/.claude/wp-malware-cleanup-mcp
cd ~/.claude/wp-malware-cleanup-mcp

# Create venv with Python 3.12
uv venv --python 3.12 .venv

# Install dependencies into venv
uv pip install -r requirements.txt

# Register globally (available in all Claude Code sessions)
claude mcp add -s user wp-malware-cleanup -- \
  ~/.claude/wp-malware-cleanup-mcp/.venv/bin/python \
  ~/.claude/wp-malware-cleanup-mcp/server.py

claude mcp list
# Should show: wp-malware-cleanup: ... ✓ Connected

Close and reopen Claude Code so the new MCP tools are loaded.

The claude mcp add command in Step 4 automatically writes to ~/.claude.json:

{
  "mcpServers": {
    "wp-malware-cleanup": {
      "command": "/Users/YOU/.claude/wp-malware-cleanup-mcp/.venv/bin/python",
      "args": ["/Users/YOU/.claude/wp-malware-cleanup-mcp/server.py"]
    }
  }
}

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "wp-malware-cleanup": {
      "command": "/Users/YOU/.claude/wp-malware-cleanup-mcp/.venv/bin/python",
      "args": ["/Users/YOU/.claude/wp-malware-cleanup-mcp/server.py"]
    }
  }
}

Note: Replace /Users/YOU with your actual home directory path.

The server stores data in ~/.wp-malware-cleanup/:

~/.wp-malware-cleanup/
├── sites.json          # Site configurations
├── quarantine/         # Quarantined malicious files
├── reports/            # Generated cleanup reports
└── logs/               # Per-site action logs

After setup, restart Claude Code and use these tools in conversation:

With password auth (common for InstaWP, managed hosting):

wp_add_site(
    name="my-site",
    host="147.182.198.163",
    username="sshuser",
    wp_path="/home/sshuser/web/example.com",
    auth_type="password",
    site_url="https://example.com"
)

With SSH key auth (recommended for production):

wp_add_site(
    name="client-blog",
    host="example.com",
    username="deploy",
    wp_path="/var/www/html",
    auth_type="key",
    key_path="~/.ssh/id_rsa"
)

# Password auth - provide password each time (not stored on disk for security)
wp_test_connection("my-site", password="your-ssh-password")

# Key auth - no password needed
wp_test_connection("client-blog")

Security note: Passwords are never stored on disk. They are passed via the SSHPASS environment variable at runtime and discarded after the SSH session ends.

wp_full_scan("my-site", password="your-ssh-password")

wp_list_sites()

Anonymized malware case studies are available in docs/case-studies/. These document real-world infections with:

• Detection signatures and IOCs
• Code analysis and behavior
• Remediation steps
• Lessons learned

# Site with SSH key
wp_add_site(
    name="site1",
    host="server1.example.com",
    username="deploy",
    wp_path="/var/www/site1",
    auth_type="key",
    key_path="~/.ssh/id_rsa"
)

# Site with different port
wp_add_site(
    name="site2",
    host="server2.example.com",
    port=2222,
    username="admin",
    wp_path="/home/admin/public_html",
    auth_type="key",
    key_path="~/.ssh/server2_key"
)

# Scan all sites
wp_batch_scan()

# Scan only pending sites
wp_batch_scan(status_filter="pending")

# 1. Backup first!
wp_backup_database("infected-site")

# 2. Run full scan
wp_full_scan("infected-site")

# 3. Audit suspicious users
wp_list_admins("infected-site")
wp_audit_user("infected-site", "suspicious_user")

# 4. Delete malicious user
wp_delete_user("infected-site", "suspicious_user", "real_admin", confirm=True)

# 5. Clean malicious files
wp_clean_uploads_php("infected-site", confirm=True)
wp_remove_mu_plugin("infected-site", "malware.php")

# 6. Reinstall core and plugins (confirm=True required for destructive tools)
wp_reinstall_core("infected-site", confirm=True)

# 7. Harden security (confirm=True required)
wp_reset_passwords("infected-site", confirm=True)
wp_regenerate_salts("infected-site", confirm=True)
wp_disable_file_editing("infected-site")
wp_add_security_htaccess("infected-site")

# 8. Update everything
wp_update_all("infected-site")

# 9. Verify cleanup
wp_full_scan("infected-site")

# 10. Generate report
wp_generate_report("infected-site")

# Preview what will happen (dry run — no changes made)
wp_complete_cleanup("infected-site")

# Review the manifest, then execute
wp_complete_cleanup("infected-site", confirm=True)

1. Backup Database

   wp_backup_database("site-name")
   

2. Run Full Scan

   wp_full_scan("site-name")
   

3. Check Recently Modified Files

   wp_scan_recently_modified("site-name", days=14)
   

1. List Admin Users

   wp_list_admins("site-name")
   

2. Find Recent Users

   wp_find_recent_users("site-name", days=30)
   

3. Audit Suspicious Users

   wp_audit_user("site-name", "suspicious_username")
   

4. Delete Malicious Users

   wp_delete_user("site-name", "hacker", "legitimate_admin", confirm=True)
   

1. Clean Uploads Directory

   wp_clean_uploads_php("site-name", confirm=True)
   

2. Remove Malicious MU-Plugins

   wp_scan_mu_plugins("site-name")
   wp_remove_mu_plugin("site-name", "malware.php")
   

3. Quarantine Suspicious Files

   wp_quarantine_file("site-name", "/full/path/to/file.php")
   

1. Reinstall WordPress Core (preview first, then confirm)

   wp_reinstall_core("site-name")              # Preview manifest
   wp_reinstall_core("site-name", confirm=True) # Execute
   

2. Verify Core Files

   wp_verify_core("site-name")
   

3. Reinstall Affected Plugins

   wp_reinstall_plugin("site-name", "plugin-slug")
   

1. Reset All Passwords (preview first, then confirm)

   wp_reset_passwords("site-name")              # Preview affected users
   wp_reset_passwords("site-name", confirm=True) # Execute
   

   Save the new passwords securely!

2. Regenerate Salts (preview first, then confirm)

   wp_regenerate_salts("site-name")              # Preview
   wp_regenerate_salts("site-name", confirm=True) # Execute
   

3. Disable File Editing

   wp_disable_file_editing("site-name")
   

4. Add Security Rules

   wp_add_security_htaccess("site-name")
   

5. Fix Permissions

   wp_fix_permissions("site-name")
   

1. Update Everything

   wp_update_all("site-name")
   

2. Final Verification Scan

   wp_full_scan("site-name")
   

3. Generate Report

   wp_generate_report("site-name")
   

Always use SSH keys instead of passwords:

# Generate SSH key
ssh-keygen -t ed25519 -C "malware-cleanup"

# Copy to server
ssh-copy-id -i ~/.ssh/id_ed25519 user@server

• Site configurations are stored locally in ~/.wp-malware-cleanup/
• Passwords are NEVER stored - provide them at runtime
• Quarantined files are kept on the remote server
• Reports may contain sensitive information - store securely

• Use a dedicated SSH user for cleanup operations
• Grant only necessary permissions
• Consider using sudo for specific WP-CLI commands

All actions are logged to ~/.wp-malware-cleanup/logs/{site-name}.log

1. Verify the hostname and port are correct
2. Check if SSH is running on the server
3. Verify firewall allows SSH connections
4. Test manually: ssh -p PORT user@host

Install WP-CLI on the WordPress server:

curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp

1. Check SSH key permissions: chmod 600 ~/.ssh/id_rsa
2. Verify the user has access to the WordPress directory
3. Check if the user can run WP-CLI: wp --info

If using password authentication:

• Ubuntu/Debian: sudo apt install sshpass
• macOS: brew install hudochenkov/sshpass/sshpass
• Recommended: Use SSH keys instead

For large sites, increase the timeout:

• Database exports may take longer
• Full scans on large sites need more time
• Consider running scans during low-traffic periods

Some legitimate code may trigger false positives:

• Base64 encoding in plugins (e.g., for image handling)
• Minified JavaScript
• Vendor libraries

Review each finding manually before taking action.

This project includes a threat intelligence database that automatically learns from every cleanup. No manual steps required — every scan and cleanup action feeds data back into the local DB.

Every detection and cleanup action is automatically recorded to the threat database:

This means:

• Quarantined files are auto-recognized if the same hash appears on another site
• cleanup_records builds a searchable history of every action across all sites
• All recording is best-effort — a DB failure never blocks a cleanup operation

Sync with community-contributed signatures and contribute back:

# Sync latest signatures from GitHub
wp_threat_db_sync()

# Check current database stats (includes cleanup_records count)
wp_threat_db_stats()

# After confirming malware, teach the system
wp_threat_learn_from_cleanup("/path/to/malware.php", "abc123hash", "backdoor", "Description")

# Export for contribution
wp_threat_export()

• Secure Random Filenames: All backup files, reports, and quarantine directories use cryptographically secure random names to prevent attackers from guessing file locations
• Restricted Permissions: Quarantine and backup directories are created with 700 permissions
• No Predictable Paths: File naming uses SHA256-based random tokens

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

To contribute malware signatures:

1. Use wp_threat_export() to export your local signatures
2. Fork this repository
3. Add your signatures to community-signatures.json or community-hashes.json
4. Submit a pull request with a description of what malware the signatures detect

Guidelines:

• Only submit confirmed malware signatures
• Include clear descriptions
• Test for false positives before submitting
• Do not include sensitive information

git clone https://github.com/vapvarun/wp-malware-cleanup-mcp.git
cd wp-malware-cleanup-mcp
pip install -e .

python -m pytest tests/

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

Author: Varun Dubey Company: Wbcom Designs

• Model Context Protocol (MCP) - Protocol for LLM integrations
• WP-CLI - Command-line interface for WordPress
• FastMCP - Python MCP server framework

• WordPress Security Team for security best practices
• The WP-CLI community for the excellent command-line tool
• Anthropic for the Model Context Protocol specification

For support, questions, or custom development:

• Website: https://wbcomdesigns.com
• GitHub Issues: Report a bug

• Auto-learning pipeline — every scan/cleanup action auto-records to threat DB
• Cross-site hash recognition — quarantined files are auto-detected on other sites
• SSH connection pooling and thread-safe DB connections
• Signature caching with TTL and pre-compiled regex
• New tools: wp_scan_hidden_plugins, wp_scan_themes, wp_clean_core_injections, wp_delete_malware_options, wp_revoke_app_passwords, wp_complete_cleanup, wp_scan_hidden_admins, wp_scan_app_passwords, wp_scan_webshells, wp_harden_wpconfig, wp_install_security_mu_plugin, wp_full_harden, wp_generate_case_study
• Patchstack and WPScan feed integration
• Anonymized case study generation
• v2 config, models, and utils modules

• Initial release
• Multi-site management
• Comprehensive malware scanning
• User audit capabilities
• Safe cleanup operations
• Security hardening tools
• Batch operations
• Detailed reporting