opn-mcp

opn-mcp

Un servidor MCP para opn.onl — el acortador de URL de código abierto y autoalojable. Permite a los asistentes de IA (Claude Desktop, Cursor, etc.) acortar enlaces, leer análisis, generar códigos QR y gestionar enlaces en lenguaje natural.

Funciona con el servicio alojado o con tu propia instancia autoalojada.

Configuración

1. Obtén una clave de API

En tu instancia de opn.onl, ve a Settings → API Keys, crea una clave y cópiala (empieza con opn_ y se muestra una sola vez).

2. Añade el servidor a tu cliente MCP

Claude Desktop — edita claude_desktop_config.json (~/Library/Application Support/Claude/ en macOS, %APPDATA%\Claude\ en Windows):

{
  "mcpServers": {
    "opn": {
      "command": "npx",
      "args": ["-y", "opn-mcp"],
      "env": {
        "OPN_API_KEY": "opn_your_key_here"
      }
    }
  }
}

Reinicia tu cliente. Eso es todo: se comunica con la API alojada (https://l.opn.onl) por defecto.

¿Prefieres ejecutarlo desde el código fuente? Cambia el args por la compilación de GitHub — misma configuración: "args": ["-y", "github:ysalitrynskyi/opn-mcp"] (se compila al instalar).

Instancia autoalojada

Apunta OPN_BASE_URL al host de API de tu propia instancia:

{
  "mcpServers": {
    "opn": {
      "command": "npx",
      "args": ["-y", "opn-mcp"],
      "env": {
        "OPN_API_KEY": "opn_your_key_here",
        "OPN_BASE_URL": "https://l.your-domain.com"
      }
    }
  }
}

Configuración

Variable de entorno	Requerida	Por defecto	Descripción
OPN_API_KEY	✅	—	Tu clave de API (opn_…), desde Settings → API Keys
OPN_BASE_URL	—	https://l.opn.onl	URL base de la API — configúrala para una instancia autoalojada

Herramientas

Enlaces

Herramienta	Descripción
shorten_url	Crea un enlace corto — alias opcional, título, notas, programación (starts_at/expires_at), max_clicks, contraseña, autodestrucción tras lectura, carpeta y etiquetas
shorten_urls_bulk	Acorta varias URL a la vez, opcionalmente en una carpeta
list_links	Lista tus enlaces (límite, desplazamiento, búsqueda, filtro por carpeta o etiqueta)
update_link	Actualiza destino, título, notas, programación, límite de clics, carpeta o protecciones; limpia campos con las banderas remove_*
delete_link	Elimina un enlace
clone_link	Duplica un enlace con un código corto nuevo
toggle_link_pin	Fija o desfija un enlace
check_alias_available	Comprueba si un alias personalizado está disponible antes de usarlo

Análisis

Herramienta	Descripción
get_link_stats	Análisis por enlace (clics, visitantes únicos, geolocalización, ciudades, dispositivos, navegadores, SO, referentes); ventana days opcional
get_dashboard_stats	Análisis de toda la cuenta en todos tus enlaces

Ayudantes de QR y URL

Herramienta	Descripción
get_qr_code	Obtén la imagen QR de un enlace — color de marca opcional, logotipo central, PNG/SVG
check_url_health	Comprueba que una URL de destino sea accesible antes de acortarla
build_utm_url	Añade parámetros de campaña UTM a una URL
preview_url_metadata	Obtén metadatos Open Graph (título, descripción, imagen) de una URL

Etiquetas y carpetas

Herramienta	Descripción
list_tags / create_tag	Lista o crea etiquetas
add_tags_to_link / remove_tags_from_link	Adjunta o desadjunta etiquetas en un enlace
list_folders / create_folder	Lista o crea carpetas
move_links_to_folder	Mueve enlaces a una carpeta

Ejemplos de prompts

• "Acorta https://example.com/very/long/url y llámalo launch-2026"
• "Acorta estas cinco URL en una nueva carpeta llamada Q3 Campaign"
• "¿Cuántos clics recibió el enlace 42 en los últimos 30 días y desde qué países?"
• "Dame un código QR SVG con marca para el enlace 42"
• "Etiqueta mis últimos 10 enlaces como 'newsletter' y muestra mis estadísticas del panel"
• "Crea un enlace UTM para https://example.com — source newsletter, medium email"

Desarrollo

npm install
npm run build      # tsc → dist/
npm test           # vitest
OPN_API_KEY=opn_… npm run dev   # run from source (stdio)

Publicación

Los tres registros pertenecen a ysalitrynskyi (usuario de npm, usuario de GitHub y el espacio de nombres io.github.ysalitrynskyi del registro MCP), por lo que la publicación debe hacerse con la sesión iniciada en esa cuenta.

1. Incrementa la versión en tres lugares y mantenlos idénticos: package.json, server.json (de nivel superior y el packages[0].version), y SERVER_VERSION en src/server.ts.
2. Haz el commit en main y haz push. CI (.github/workflows/ci.yml) ejecuta build + test — no publica.
3. Publica en npm (como usuario de npm ysalitrynskyi):

   npm login
   npm publish        # prepublishOnly runs the build
   

4. Publica en el registro MCP (como usuario de GitHub ysalitrynskyi):

   mcp-publisher validate      # optional, offline check
   mcp-publisher login github  # interactive browser OAuth
   mcp-publisher publish
   

Smithery (smithery.yaml) y Glama (glama.json) siguen la publicación de npm/registro automáticamente — no se necesita ningún paso adicional.

Licencia

MIT © ysalitrynskyi. Parte del proyecto opn.onl.