WordPress MCP Server
# WordPress MCP Server
[](https://github.com/modelcontextprotocol)
[](https://www.python.org/)
[](https://wordpress.org/)
[](LICENSE)
[](https://rodrigo.us)
[](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
Scored across 17 tools
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.
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.
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.
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.