YOURLS-MCP

Integra el servicio de acortamiento de URLs YOURLS con Claude Desktop.

Documentación

YOURLS-MCP

Un servidor de Protocolo de Control de Modelos (MCP) para integrar el acortador de URLs YOURLS con Claude Desktop.

Autor: Martin Kessler

Descripción general

YOURLS-MCP crea un puente entre Claude Desktop y tu instancia de acortador de URLs YOURLS autoalojada. Cuando está configurado, permite que Claude acorte URLs automáticamente usando tu instalación personal de YOURLS.

Características

Acorta URLs usando tu instancia de YOURLS
Crea URLs cortas personalizadas con palabras clave específicas
Manejo de URLs duplicadas: Crea múltiples URLs cortas para la misma URL de destino (exclusivo de YOURLS-MCP)
Información ampliada de URLs y estadísticas
Estadísticas de la base de datos
Alternativas inteligentes para plugins
Documentación completa y herramientas de prueba

Inicio rápido

Instalación

# Clone the repository
git clone https://github.com/kesslerio/yourls-mcp.git
cd yourls-mcp

# Install dependencies
npm install

Configuración

Crea un archivo de configuración de Claude Desktop que apunte a tu instalación de YOURLS-MCP:

{
  "mcpServers": {
    "yourls": {
      "command": "node",
      "args": [
        "/full/path/to/yourls-mcp/yourls-mcp.js"
      ],
      "env": {
        "YOURLS_API_URL": "https://your-yourls-domain.com/yourls-api.php",
        "YOURLS_AUTH_METHOD": "signature", 
        "YOURLS_SIGNATURE_TOKEN": "your-secret-signature-token"
      }
    }
  }
}

Guarda este archivo en el directorio de configuración de Claude Desktop, que normalmente se encuentra en:

macOS: ~/Library/Application Support/Claude/config.json
Windows: %APPDATA%\Claude\config.json
Linux: ~/.config/Claude/config.json

Características

Integración perfecta con Claude Desktop mediante MCP
Acorta URLs directamente a través de Claude
Expande URLs acortadas para ver su destino
Obtén estadísticas de clics para tus enlaces
Soporte de palabras clave personalizadas
Autenticación segura basada en firmas
Configuración mediante variables de entorno

Opciones de configuración

Las siguientes variables de entorno se pueden establecer en la configuración de Claude Desktop:

Variable	Descripción	Predeterminado	Obligatorio
`YOURLS_API_URL`	URL de tu endpoint de API de YOURLS	-	Sí
`YOURLS_AUTH_METHOD`	Método de autenticación (`signature` o `password`)	`signature`	No
`YOURLS_SIGNATURE_TOKEN`	Token secreto para autenticación basada en firmas	-	Sí (si se usa autenticación por firma)
`YOURLS_USERNAME`	Nombre de usuario para autenticación por contraseña	-	Sí (si se usa autenticación por contraseña)
`YOURLS_PASSWORD`	Contraseña para autenticación por contraseña	-	Sí (si se usa autenticación por contraseña)
`YOURLS_SIGNATURE_TTL`	Tiempo de vida de las firmas en segundos	43200 (12 horas)	No

Herramientas MCP disponibles

YOURLS-MCP proporciona las siguientes herramientas a Claude:

Herramientas principales

1. shorten_url

Acorta una URL larga usando tu instancia de YOURLS.

Parámetros:

url (obligatorio): La URL larga a acortar
keyword (opcional): Palabra clave personalizada para la URL corta
title (opcional): Título para la URL

2. expand_url

Expande una URL corta para obtener la URL larga original.

Parámetros:

shorturl (obligatorio): La URL corta o palabra clave a expandir

3. url_stats

Obtiene estadísticas para una URL acortada.

Parámetros:

shorturl (obligatorio): La URL corta o palabra clave para obtener estadísticas

4. db_stats

Obtiene estadísticas globales de tu instancia de YOURLS.

Parámetros: Ninguno

5. create_custom_url

Crea una URL corta personalizada con una palabra clave específica, incluso para URLs que ya existen en la base de datos.

Parámetros:

url (obligatorio): La URL de destino a acortar
keyword (obligatorio): La palabra clave personalizada para la URL corta (por ejemplo, "web" para bysha.pe/web)
title (opcional): Título para la URL
bypass_shortshort (opcional): Si se debe omitir el plugin ShortShort que evita acortar URLs ya acortadas (predeterminado: false)
force_url_modification (opcional): Si se debe forzar el enfoque de modificación de URL para crear múltiples URLs cortas para el mismo destino (predeterminado: false)

6. shorten_with_analytics

Acorta una URL larga con parámetros UTM de Google Analytics.

Parámetros:

url (obligatorio): La URL a acortar
source (obligatorio): Parámetro UTM source - identifica la fuente del tráfico (por ejemplo, "google", "newsletter", "twitter")
medium (obligatorio): Parámetro UTM medium - identifica el medio de marketing (por ejemplo, "cpc", "social", "email")
campaign (obligatorio): Parámetro UTM campaign - identifica la campaña específica (por ejemplo, "summer_sale", "product_launch")
term (opcional): Parámetro UTM term - identifica términos de búsqueda pagados
content (opcional): Parámetro UTM content - diferencia anuncios o enlaces que apuntan a la misma URL
keyword (opcional): Palabra clave personalizada para la URL corta
title (opcional): Título para la URL

Herramientas basadas en plugins

7. url_analytics

Obtiene análisis detallados de clics para una URL corta dentro de un rango de fechas. Requiere que el plugin API ShortURL Analytics esté instalado.

Parámetros:

shorturl (obligatorio): La URL corta o palabra clave para obtener análisis
date (obligatorio): Fecha de inicio para el análisis en formato YYYY-MM-DD
date_end (opcional): Fecha de fin para el análisis en formato YYYY-MM-DD (se usa la fecha de inicio si no se proporciona)

8. contract_url

Comprueba si una URL ya ha sido acortada sin crear una nueva URL corta. Requiere que el plugin API Contract esté instalado.

Parámetros:

url (obligatorio): La URL a comprobar si ha sido acortada

9. update_url

Actualiza una URL corta existente para que apunte a una URL de destino diferente. Requiere que el plugin API Edit URL esté instalado.

Parámetros:

shorturl (obligatorio): La URL corta o palabra clave a actualizar
url (obligatorio): La nueva URL de destino
title (opcional): Nuevo título opcional ("keep" para mantener el existente, "auto" para obtenerlo de la URL)

10. change_keyword

Cambia la palabra clave de una URL corta existente. Requiere que el plugin API Edit URL esté instalado.

Parámetros:

oldshorturl (obligatorio): La URL corta o palabra clave existente
newshorturl (obligatorio): La nueva palabra clave a usar
url (opcional): URL opcional (si no se proporciona, se usará la URL de oldshorturl)
title (opcional): Nuevo título opcional ("keep" para mantener el existente, "auto" para obtenerlo de la URL)

11. get_url_keyword

Obtiene la(s) palabra(s) clave para una URL larga. Requiere que el plugin API Edit URL esté instalado.

Parámetros:

url (obligatorio): La URL larga a buscar
exactly_one (opcional): Si es false, devuelve todas las palabras clave para esta URL (predeterminado: true)

12. delete_url

Elimina una URL corta. Requiere que el plugin API Delete esté instalado.

Parámetros:

shorturl (obligatorio): La URL corta o palabra clave a eliminar

13. list_urls

Obtiene una lista de URLs con opciones de ordenación, paginación y filtrado. Requiere que el plugin API List Extended esté instalado.

Parámetros:

sortby (opcional): Campo para ordenar (keyword, url, title, ip, timestamp, clicks) (predeterminado: timestamp)
sortorder (opcional): Orden de clasificación (ASC o DESC) (predeterminado: DESC)
offset (opcional): Desplazamiento de paginación (predeterminado: 0)
perpage (opcional): Número de resultados por página (predeterminado: 50)
query (opcional): Consulta de búsqueda opcional para filtrar por palabra clave
fields (opcional): Campos a devolver (keyword, url, title, timestamp, ip, clicks) (predeterminado: todos los campos)

14. generate_qr_code

Genera un código QR para una URL acortada. Requiere que el plugin YOURLS-IQRCodes esté instalado.

Parámetros:

shorturl (obligatorio): La URL corta o palabra clave para generar un código QR
size (opcional): Tamaño del código QR en píxeles
border (opcional): Ancho del borde alrededor del código QR
ecc (opcional): Nivel de corrección de errores: L (bajo), M (medio), Q (cuartil) o H (alto)
format (opcional): Formato de imagen (png, jpg, svg, etc.)

Ejemplos de uso

Una vez configurado, Claude podrá usar las herramientas de YOURLS con indicaciones como:

Ejemplos de funciones principales

"Acorta esta URL para mí: https://example.com/very-long-url-that-needs-shortening"
"Crea una URL corta con la palabra clave 'docs' para https://example.com/documentation"
"Configura una URL personalizada bysha.pe/web que apunte a shapescale.com"
"Crea una URL corta personalizada para nuestra documentación usando la palabra clave 'docs'"
"Crea múltiples palabras clave (docs, docs2, docs3) para la misma URL de documentación"
"Crea una URL corta para nuestra campaña con parámetros de seguimiento UTM"
"Acorta esta URL de marketing con seguimiento de Google Analytics: source=newsletter, medium=email, campaign=summer_launch"
"Expande esta URL corta: https://yourdomain.com/abc"
"¿Cuántos clics tiene mi URL corta https://yourdomain.com/abc?"
"Muéstrame las estadísticas de mi instancia de YOURLS"

Ejemplos de funciones basadas en plugins

"Dame análisis detallados para la URL corta 'abc' de enero de 2025"
"Muéstrame las estadísticas de clics para bysha.pe/abc del 2025-01-01 al 2025-01-31"
"¿Cuál fue el tráfico diario de mi URL corta 'web' el mes pasado?"
"Comprueba si esta URL ya ha sido acortada: https://example.com/page"
"¿Alguien ya ha creado una URL corta para https://example.com/page??"
"Actualiza el destino de la URL corta 'docs' para que apunte a https://example.com/new-documentation"
"Cambia a dónde apunta la palabra clave 'docs'"
"Renombra la URL corta 'docs' a 'documentation'"
"Cambia la palabra clave de mi URL corta de 'docs' a 'documentation'"
"¿Cuál es la palabra clave para esta URL larga: https://example.com/page??"
"Lista todas las URLs cortas para https://example.com/page"
"Elimina la URL corta 'docs'"
"Elimina la palabra clave 'docs' de mi instancia de YOURLS"
"Muéstrame las 10 URLs cortas más recientes en mi base de datos de YOURLS"
"Lista todas las URLs cortas ordenadas por número de clics"
"Busca URLs cortas que contengan 'product'"
"Genera un código QR para mi URL corta 'docs'"
"Crea un código QR para bysha.pe/web"
"Dame un código QR para mi página de producto con alta corrección de errores"
"Necesito un código QR más grande para la URL corta 'landing', hazlo de 300 píxeles"
"Genera un código QR SVG para nuestro enlace de documentación"

Desarrollo

# Clone the repository
git clone https://github.com/kesslerio/yourls-mcp.git
cd yourls-mcp

# Install dependencies
npm install

# For local testing, create a claude-local-config.json file:
{
  "mcpServers": {
    "yourls": {
      "command": "node",
      "args": [
        "/full/path/to/yourls-mcp/yourls-mcp.js"
      ],
      "env": {
        "YOURLS_API_URL": "https://your-yourls-domain.com/yourls-api.php",
        "YOURLS_AUTH_METHOD": "signature",
        "YOURLS_SIGNATURE_TOKEN": "your-secret-signature-token"
      }
    }
  }
}

# Start the server directly (for testing)
node yourls-mcp.js

Cómo funciona

YOURLS-MCP actúa como un puente entre Claude Desktop y tu instancia de YOURLS:

Claude Desktop inicia el servidor YOURLS-MCP cuando es necesario
El servidor lee la configuración de las variables de entorno
Cuando Claude invoca una herramienta, el servidor realiza las llamadas API apropiadas a tu instancia de YOURLS
Los resultados se devuelven a Claude en un formato estructurado

El servidor utiliza el estándar de Protocolo de Contexto de Modelos (MCP) para comunicarse con Claude Desktop, permitiendo una integración perfecta e interacciones en lenguaje natural con tu acortador de URLs.

Manejo de URLs duplicadas

YOURLS-MCP ofrece una capacidad única para crear múltiples URLs cortas para la misma URL de destino, lo cual no es compatible de forma nativa en YOURLS. Para obtener información detallada sobre esta función, consulta la Documentación de manejo de URLs duplicadas.

Se admiten dos enfoques:

Enfoque de plugin (recomendado): Usa el plugin incluido Force Allow Duplicates para crear URLs duplicadas reales
Enfoque de modificación de URL (alternativa): Agrega parámetros de marca de tiempo para hacer que cada URL sea técnicamente única mientras se preserva la funcionalidad

El sistema selecciona automáticamente el enfoque apropiado según tu configuración de YOURLS.

Compatibilidad con plugins de YOURLS

YOURLS-MCP está diseñado para funcionar tanto con instalaciones estándar de YOURLS como con varios plugins, con alternativas integradas cuando los plugins no están disponibles:

Plugins compatibles con alternativas

YOURLS-MCP incluye alternativas inteligentes para funcionalidad ampliada cuando los plugins no están instalados:

API ShortURL Analytics: Para estadísticas detalladas de clics con rangos de fechas
- Comportamiento alternativo: Proporciona estadísticas básicas de clics a través de la API principal de YOURLS cuando el plugin no está disponible
API Contract: Para comprobar si las URLs existen sin crearlas
- Comportamiento alternativo: Usa la API de estadísticas principal de YOURLS para buscar URLs existentes con filtrado
API Edit URL: Para actualizar URLs cortas y cambiar palabras clave
- Comportamiento alternativo:
  - Para actualizar URLs: Intenta recrear la URL con la misma palabra clave
  - Para cambiar palabras clave: Crea una nueva URL corta con la nueva palabra clave (la anterior permanece, ya que la eliminación requiere el plugin API Delete)
  - Para obtener palabras clave de URLs: Usa la API de estadísticas principal de YOURLS con filtrado
API Delete: Para eliminar URLs cortas
- Comportamiento de respaldo: Limitado: proporciona información de que la eliminación requiere el plugin, ya que la API principal de YOURLS no admite la eliminación
API List Extended: Para listado mejorado de URLs con ordenación y filtrado
- Comportamiento de respaldo: Utiliza la API de estadísticas principal de YOURLS con ordenación y paginación en el lado del cliente
YOURLS-IQRCodes: Para generar códigos QR a partir de URLs cortas
- Comportamiento de respaldo: Ninguno: requiere que el plugin esté instalado
ShortShort: Maneja adecuadamente el error al intentar acortar una URL ya acortada
- Compatibilidad: El manejo de errores funciona independientemente de si el plugin está instalado
Allow Existing URLs: Modifica cómo YOURLS maneja URLs duplicadas
- URL del plugin: https://github.com/elder-oss/yourls-allow-existing-urls
- Nota: Este plugin cambia las respuestas de error por respuestas de éxito, pero no crea realmente nuevas URLs cortas para URLs de destino existentes
- Nuestra solución: YOURLS-MCP implementa un enfoque de modificación de URL que añade un parámetro de marca de tiempo para hacer que las URLs sean únicas en la base de datos, preservando la experiencia del usuario
- Instalación: Opcional: nuestro enfoque de modificación de URL funciona con o sin este plugin instalado
Force Allow Duplicates: Habilita realmente la creación de múltiples URLs cortas para la misma URL de destino
- Repositorio del plugin: https://github.com/kesslerio/yourls-force-allow-duplicates (próximamente)
- Descripción: Plugin personalizado que omite la restricción de URL única de YOURLS
- Uso: Añade force=1 a tus solicitudes de API o usa force_url_modification=false con la herramienta create_custom_url
- Instalación:
  1. Descarga desde el repositorio de plugins
  2. Copia la carpeta force-allow-duplicates a tu directorio YOURLS/user/plugins/
  3. Activa el plugin en la interfaz de administración de YOURLS

Mecanismo de Respaldo

Cuando se utiliza una función dependiente de un plugin pero el plugin no está instalado, YOURLS-MCP:

Detecta automáticamente los plugins faltantes
Proporciona funcionalidad de respaldo adecuada cuando es posible
Incluye un atributo fallback_used: true en las respuestas cuando se activan los respaldos
Añade información fallback_limitations cuando el respaldo tiene funcionalidad reducida
Para operaciones completamente no soportadas, devuelve mensajes de error informativos

Este enfoque garantiza que YOURLS-MCP funcione con tantas instalaciones de YOURLS como sea posible, proporcionando al mismo tiempo información clara sobre la funcionalidad mejorada disponible con los plugins.

Desarrollo y Pruebas

Scripts de Prueba

El proyecto incluye varios scripts de prueba en el directorio tests/integration/:

Pruebas de Acortamiento de URLs:
- test-custom-url.js: Prueba la creación de URLs personalizadas con palabras clave específicas
- test-url-modification.js: Prueba el enfoque de modificación de URL para manejar URLs duplicadas
- test-plugin-behavior.js: Prueba el comportamiento del plugin Allow Existing URLs
Pruebas de Plugins:
- test-duplicate-urls.js: Prueba la creación de URLs duplicadas con diferentes palabras clave
- test-plugin-approach.js: Prueba el enfoque directo del plugin para manejar duplicados

Ejecución de Pruebas:

# Run a specific test
node tests/integration/test-custom-url.js

Scripts de Utilidad

El directorio scripts/ contiene scripts de utilidad para operaciones comunes:

create-random.js: Crea una URL corta aleatoria para un destino especificado
Otros scripts para tareas específicas de creación de URLs

Licencia

MIT

Acerca de

YOURLS-MCP fue creado por Martin Kessler para integrar YOURLS con Claude Desktop y otras ofertas de Claude mediante el Protocolo de Contexto de Modelo (MCP).

El plugin Force Allow Duplicates fue desarrollado para resolver el desafío de crear múltiples URLs cortas para el mismo destino, lo cual no está soportado de forma nativa en YOURLS.

Para soporte, problemas o solicitudes de funciones:

YOURLS-MCP: https://github.com/kesslerio/yourls-mcp/issues
Plugin Force Allow Duplicates: https://github.com/kesslerio/yourls-force-allow-duplicates/issues (una vez que se cree el repositorio)