Skip to main content
Glama
WordPress MCP Server

WordPress MCP Server

by ernestoh0183
README.md
# WordPress MCP Server

[![FastMCP](https://img.shields.io/badge/FastMCP-2.0+-blue.svg)](https://github.com/modelcontextprotocol)
[![Python](https://img.shields.io/badge/Python-3.10%2B-brightgreen.svg)](https://www.python.org/)
[![WordPress](https://img.shields.io/badge/WordPress-6.0%2B-21759B.svg)](https://wordpress.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Author](https://img.shields.io/badge/Author-Rodrigo%20Ernesto%20Hernandez-blue.svg)](https://rodrigo.us)
[![Website](https://img.shields.io/badge/Website-4ruy.com-00FF66.svg)](https://4ruy.com)

Servidor de **Model Context Protocol (MCP)** basado en Python y `FastMCP` que proporciona a agentes de Inteligencia Artificial (Claude Desktop, Cursor, Antigravity, VS Code / Cline, Windsurf, etc.) control integral sobre sitios **WordPress**.

Desarrollado y mantenido por [Rodrigo Ernesto Hernandez](https://rodrigo.us) ([4Ruy.com](https://4ruy.com)).

Permite redactar y publicar artículos, gestionar taxonomías multilingües con **Polylang**, subir imágenes de portada (locales, URLs o Base64), administrar plugins con comprobación de versiones en WordPress.org, moderar y responder comentarios, y purgar cachés de forma atómica.

---

## 📋 Tabla de Contenidos

- [Características Principales](#-características-principales)
- [Arquitectura y Estructura](#-arquitectura-y-estructura)
- [Tecnologías Utilizadas](#-tecnologías-utilizadas)
- [Catálogo de Herramientas MCP (17 Tools)](#-catálogo-de-herramientas-mcp-17-tools)
- [Requisitos Previos en WordPress](#-requisitos-previos-en-wordpress)
- [Instalación y Puesta en Marcha](#-instalación-y-puesta-en-marcha)
- [Configuración en Clientes MCP](#-configuración-en-clientes-mcp)
- [Seguridad](#-seguridad)
- [Autor y Contacto](#-autor-y-contacto)
- [Licencia](#-licencia)

---

## ✨ Características Principales

1. **Gestión Editorial Completa**: Lectura contextual del blog en texto plano para evitar duplicidad de temas, creación de borradores enriquecidos en HTML, actualización de posts existentes y control del ciclo de vida (borrador, publicar, papelera o eliminación permanente).
2. **Soporte Multilingüe (Polylang Free)**: Vinculación bidireccional nativa entre entradas en distintos idiomas (`pll_save_post_translations`) y de términos taxonómicos (`pll_save_term_translations`) superando las limitaciones de la REST API estándar de Polylang Free.
3. **Taxonomías Técnicas**: CRUD de categorías y etiquetas con asignación de idioma, slugs limpios y descripciones optimizadas para SEO.
4. **Biblioteca Multimedia Inteligente**: Subida de portadas e imágenes destacadas aceptando rutas locales del sistema operativo, URLs remotas o datos codificados en Base64, con asignación automática de texto alternativo (`alt_text`) y vinculación directa al post.
5. **Administración y Auditoría de Plugins**: Listado de plugins activos e inactivos, consulta en tiempo real a la API pública de WordPress.org para verificar si existen actualizaciones disponibles, activación, desactivación y actualización de plugins.
6. **Moderación y Respuestas de Comentarios**: Consulta de comentarios por estado (aprobado, pendiente, spam), cambio de estado y publicación de respuestas oficiales anidadas en el hilo.
7. **Purgado Multinivel de Caché**: Endpoint optimizado para invalidar simultáneamente *WP Super Cache*, *Docket Cache* y la caché de código de bytes *OPcache* de PHP.

---

## 🏗️ Arquitectura y Estructura

```
wordpress-mcp-server/
├── wp_mcp_server.py          # Servidor FastMCP en Python (17 herramientas operativas)
├── requirements.txt          # Dependencias esenciales de Python
├── pyproject.toml            # Empaquetado y metadatos estándar de Python
├── .env.example              # Plantilla para variables de entorno de conexión
├── .gitignore                # Reglas estrictas de exclusión (ignora .env, cachés, etc.)
├── LICENSE                   # Licencia de código abierto MIT
├── README.md                 # Documentación técnica completa
└── wordpress-plugin/
    ├── README.md             # Guía de instalación del plugin puente
    └── polylang-mcp-bridge.php # Plugin WordPress para Polylang Free y purga de caché
```

---

## 🧰 Tecnologías Utilizadas

- **[FastMCP / Model Context Protocol](https://github.com/modelcontextprotocol)**: Protocolo estándar abierto que permite a los LLMs interactuar de forma segura con herramientas locales y APIs.
- **Python 3.10+**: Motor del servidor, con tipado estricto mediante anotaciones de tipo (`typing`).
- **Requests & HTTPBasicAuth**: Comunicación robusta con la REST API de WordPress usando Application Passwords.
- **WordPress REST API (v2)**: Interfaz REST estándar de WordPress para posts, taxonomías, medios, plugins y ajustes.
- **Polylang Bridge (PHP)**: Micro-plugin complementario para solventar la ausencia de endpoints nativos de vinculación en la versión gratuita de Polylang.

---

## 🛠️ Catálogo de Herramientas MCP (17 Tools)

| Módulo | Herramienta | Parámetros Principales | Descripción |
| :--- | :--- | :--- | :--- |
| **Contenido** | `leer_contexto_blog` | `limite` (int, default 5), `idioma` (opcional: 'es', 'en') | Obtiene los artículos recientes en texto plano para contextualizar estilo y evitar temas repetidos. |
| **Contenido** | `publicar_borrador_wp` | `titulo`, `contenido_html`, `slug`, `resumen`, `categorias`, `etiquetas`, `imagen_portada_id`, `idioma`, `post_traduccion_id` | Crea o actualiza una entrada en estado borrador con metadatos completos y asignación de idioma. |
| **Contenido** | `actualizar_post` | `post_id`, `titulo`, `contenido_html`, `slug`, `resumen`, `estado`, `categorias`, `etiquetas`, `imagen_portada_id` | Actualiza selectivamente cualquier campo de una entrada existente. |
| **Contenido** | `gestionar_post` | `post_id`, `accion` (`publicar`, `borrador`, `papelera`, `eliminar`) | Gestiona el ciclo de vida y visibilidad de un post. |
| **Polylang** | `vincular_traducciones_polylang` | `post_id_es`, `post_id_en` | Enlaza dos publicaciones como traducciones recíprocas Español/Inglés en Polylang Free. |
| **Taxonomías** | `gestionar_categoria` | `accion` (`crear`, `actualizar`, `eliminar`, `listar`), `nombre`, `slug`, `descripcion`, `categoria_id`, `idioma` | Operaciones CRUD completas para categorías con soporte multilingüe. |
| **Taxonomías** | `gestionar_etiqueta` | `accion` (`crear`, `actualizar`, `eliminar`, `listar`), `nombre`, `slug`, `descripcion`, `etiqueta_id`, `idioma` | Operaciones CRUD completas para etiquetas (tags). |
| **Taxonomías** | `vincular_terminos_polylang` | `termino_id_es`, `termino_id_en`, `taxonomia` (`category` o `post_tag`) | Vincula dos términos como traducciones directas en Polylang Free. |
| **Medios** | `subir_imagen_portada` | `origen_imagen` (ruta de archivo local, URL HTTP o datos Base64), `nombre_archivo`, `texto_alt`, `post_id` | Sube una imagen a la biblioteca de medios y opcionalmente la asigna como destacada. |
| **Caché** | `purgar_cache_sitio` | *(Ninguno)* | Invalida de forma atómica WP Super Cache, Docket Cache y OPcache. |
| **Plugins** | `revisar_plugins` | `verificar_actualizaciones` (bool, default True) | Lista plugins instalados (activos/inactivos) y consulta actualizaciones en WordPress.org. |
| **Plugins** | `administrar_plugin` | `plugin_slug`, `accion` (`activar`, `desactivar`, `actualizar`, `eliminar`) | Modifica el estado o actualiza cualquier plugin instalado. |
| **Comentarios**| `revisar_comentarios` | `estado` (`all`, `approved`, `hold`, `spam`, `trash`), `limite`, `post_id` | Lista comentarios con filtros por estado o por post. |
| **Comentarios**| `moderar_comentario` | `comentario_id`, `accion` (`aprobar`, `mantener`, `spam`, `papelera`, `eliminar`) | Aplica acciones de moderación sobre comentarios de usuarios. |
| **Comentarios**| `responder_comentario` | `comentario_id`, `post_id`, `contenido` | Publica una respuesta oficial anidada en el hilo de discusión. |
| **Ajustes** | `obtener_configuraciones` | *(Ninguno)* | Consulta metadatos globales del sitio (título, descripción, zona horaria, URL, etc.). |
| **Ajustes** | `actualizar_configuracion` | `titulo`, `descripcion`, `zona_horaria`, `formato_fecha`, `formato_hora`, `site_logo_id` | Actualiza configuraciones generales de WordPress. |

---

## 🔑 Requisitos Previos en WordPress

### 1. Generar una Contraseña de Aplicación (Application Password)
WordPress incluye soporte nativo para Application Passwords desde la versión 5.6:
1. Inicia sesión en el panel de control de WordPress con un usuario Administrador o Editor.
2. Dirígete a **Usuarios** > **Tu perfil**.
3. Desplázate hacia abajo hasta la sección **Contraseñas de aplicación**.
4. Escribe un nombre descriptivo (por ejemplo: `MCP Server`) y pulsa en **Añadir nueva contraseña de aplicación**.
5. Copia la contraseña de 24 caracteres generada (ej: `xxxx xxxx xxxx xxxx xxxx xxxx`).

> [!NOTE]
> La contraseña de aplicación no expone tu contraseña personal y puede ser revocada en cualquier momento desde el mismo panel.

### 2. Instalar el Plugin Puente para Polylang y Caché (Opcional pero recomendado)
Si utilizas **Polylang** o sistemas de caché en servidor:
1. Copia el archivo `wordpress-plugin/polylang-mcp-bridge.php` en la carpeta `wp-content/plugins/polylang-mcp-bridge/` de tu instalación de WordPress.
2. Activa el plugin **WordPress MCP REST Bridge (Polylang & Cache)** desde el menú **Plugins** de WordPress.

---

## 🚀 Instalación y Puesta en Marcha

### 1. Clonar el Repositorio
```bash
git clone https://github.com/ernestoh0183/wordpress-mcp-server.git
cd wordpress-mcp-server
```

### 2. Configurar el Entorno Virtual de Python
```bash
# Crear entorno virtual
python -m venv .venv

# Activar en Windows (PowerShell):
.\.venv\Scripts\Activate.ps1

# Activar en Linux/macOS:
source .venv/bin/activate

# Instalar dependencias
pip install -r requirements.txt
```

### 3. Configurar Credenciales (`.env`)
Copia la plantilla `.env.example`:
```bash
cp .env.example .env
```
Edita `.env` con los datos de tu sitio:
```ini
WP_URL=https://your-wordpress-site.com
WP_USER=your_username
WP_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx
```

---

## 🔌 Configuración en Clientes MCP

### Claude Desktop
Edita tu archivo de configuración de Claude Desktop:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "wordpress": {
      "command": "python",
      "args": ["C:/ruta/a/wordpress-mcp-server/wp_mcp_server.py"],
      "env": {
        "WP_URL": "https://your-wordpress-site.com",
        "WP_USER": "your_username",
        "WP_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
      }
    }
  }
}
```

### Cursor
En Cursor, abre **Settings** > **Features** > **MCP Servers** y añade un nuevo servidor:
- **Name**: `wordpress`
- **Type**: `command`
- **Command**: `python C:/ruta/a/wordpress-mcp-server/wp_mcp_server.py`

### Antigravity / Gemini CLI
Añade a tu configuración en `mcp_config.json`:
```json
{
  "mcpServers": {
    "wordpress": {
      "command": "python",
      "args": ["C:/ruta/a/wordpress-mcp-server/wp_mcp_server.py"],
      "env": {
        "WP_URL": "https://your-wordpress-site.com",
        "WP_USER": "your_username",
        "WP_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
      }
    }
  }
}
```

---

## 🔒 Seguridad

- **Sin credenciales maestras**: Se apoya exclusivamente en *Application Passwords* con autenticación HTTP Basic sobre TLS/HTTPS.
- **Protección de `.env`**: El archivo `.env` está expresamente excluido en `.gitignore` para evitar filtraciones accidentales de credenciales.
- **Validación de entradas**: Todos los slugs, IDs y contenidos HTML son sanitizados y validados antes de transmitirse a la REST API de WordPress.
- **Permisos de usuario**: Cada endpoint respeta los roles y capacidades del usuario autenticado en WordPress (`edit_posts`, `manage_categories`, `manage_options`).

---

## 👨‍💻 Autor y Contacto

Creado y mantenido por **Rodrigo Ernesto Hernandez**.

Si buscas consultoría, integración personalizada de agentes de IA con WordPress, desarrollo a medida o automatización de flujos de trabajo editoriales para tu empresa, puedes contactarme directamente:

* 🌐 **Sitio Web Personal:** [rodrigo.us](https://rodrigo.us)
* 🚀 **Portal Tecnológico:** [4ruy.com](https://4ruy.com)
* ✉️ **Correo Electrónico:** [rodrigo@4ruy.com](mailto:rodrigo@4ruy.com) / [rodrigo@rodrigo.us](mailto:rodrigo@rodrigo.us)

¿Te resulta útil este proyecto? Dale una ⭐ en GitHub y compártelo.

---

## 📄 Licencia

Este proyecto es de código abierto y está distribuido bajo la Licencia **MIT**. Creado por **Rodrigo Ernesto Hernandez** (© 2026). Consulta el archivo [LICENSE](LICENSE) para más detalles.

TDQS

A3.5/5.0

Scored across 17 tools

Disambiguation3/5

Most tools are clearly distinct (settings vs. media vs. plugins vs. comments), but three post tools overlap: publicar_borrador_wp can both create and update via post_id, actualizar_post updates many of the same fields including estado, and gestionar_post also changes status/delete. An agent could reasonably be unsure whether to update a post with publicar_borrador_wp, actualizar_post, or gestionar_post.

Naming Consistency4/5

Nearly all names follow a Spanish verb_noun pattern (obtener_configuraciones, actualizar_post, gestionar_categoria, revisar_comentarios), which is predictable. Minor deviations exist: the _wp suffix on publicar_borrador_wp, singular vs. plural (revisar_plugins / administrar_plugin), and English nouns (post, plugin) mixed with Spanish verbs.

Tool Count4/5

17 tools is slightly above the ideal range but each covers a distinct area (posts, taxonomies, translations, media, plugins, comments, settings, cache). The set is well-scoped for a full WordPress management server rather than padded.

Completeness4/5

Core lifecycle is well covered: post create/update/publish/delete, category and tag CRUD, comment list/moderate/reply, plugin list/manage, media upload, settings get/update, and cache purge. Minor gaps remain, such as fetching a single post by ID, listing/deleting media, and menu or user management.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues