Listable

Crear sitios web de directorio a través de MCP

Documentación

Servidor MCP de Listable

Permite que Claude, Cursor y otros asistentes de IA gestionen tu sitio de directorio Listable mediante conversación natural.

Listable es una plataforma para crear sitios de directorio: guías de restaurantes, directorios de negocios, listados de viajes, sitios curados de nicho. Su servidor MCP (Model Context Protocol) expone cada operación de gestión del sitio como una herramienta estructurada que los asistentes de IA pueden invocar.

Pregúntale a la IA cosas como:

"Añade 20 restaurantes italianos en Brooklyn a mi directorio de comida."
"Importa estos listados desde el CSV que estoy pegando."
"Configura el título meta SEO y la descripción para la página de inicio."
"Añade un menú desplegable de Categorías al encabezado."
"Crea una página Acerca de con nuestra misión y una lista de listados destacados."

Qué puede hacer

~47 herramientas agrupadas en estas categorías:

Grupo	Herramientas
Proyectos	listar, obtener, descubrimiento de esquema
Elementos (listados)	listar (paginado, filtrado), obtener, crear, actualizar, eliminar, bulk_create (hasta 100/llamada)
Categorías	CRUD completo, árboles de categorías, inspección de conflictos
Campos personalizados	listar, crear, actualizar, eliminar (texto, número, fecha, url, casilla de verificación, selección, teléfono, dirección, imagen)
Páginas + bloques	listar páginas, obtener/actualizar bloques de página, gestionar áreas de bloques globales (héroe de inicio, principal de inicio, página de detalle, páginas de categoría)
Formularios	listar, obtener, crear, actualizar, eliminar; gestionar campos de formulario
Configuración	menú, scripts, SEO, estructura de URL, tema
Redirecciones	CRUD completo
Subidas	subir imágenes/archivos para usar en listados y páginas

Se le indica a la IA que llame a get_schema primero para que sus ediciones usen los campos personalizados y tipos de bloque correctos. Las operaciones destructivas (eliminaciones, reemplazos completos de bloques, cambios de estructura de URL, sobrescrituras de scripts) solicitan confirmación antes de ejecutarse.

Dos formas de conectarse

	OAuth (recomendado)	Clave API estática (este paquete)
Cómo funciona la autenticación	El cliente abre un navegador, inicias sesión en Listable, eliges qué proyectos conceder, listo	Creas una clave en el panel de administración, la pegas en la configuración del cliente
Funciona con	Claude.ai web, Claude Code, Cursor, cualquier cliente que admita HTTP MCP + descubrimiento OAuth	Claude Desktop (sin transporte HTTP), o en cualquier lugar donde quieras una conexión con token estático
Configuración	Pega una URL	Instala este paquete + crea + pega una clave

Si tu cliente admite transporte HTTP MCP, omite el shim por completo: consulta Configuración de OAuth a continuación. El paquete npm (listable-mcp) solo es necesario para clientes solo-stdio como Claude Desktop.

Configuración de OAuth (sin instalación necesaria)

El endpoint MCP es:

https://app.get-listable.com/api/v1/external/mcp

Cuando un cliente se conecta sin un token de portador, el servidor devuelve un 401 más una pista de descubrimiento WWW-Authenticate que apunta a /.well-known/oauth-protected-resource. El cliente la sigue, te redirige para iniciar sesión, te pide aprobar los alcances (incluyendo qué proyectos conceder) y obtiene un token automáticamente. Los tokens de acceso expiran después de 1 hora y se renuevan silenciosamente durante 1 mes.

Claude.ai (web)

Configuración → Integraciones → Añadir integración personalizada → pega:

https://app.get-listable.com/api/v1/external/mcp

Claude.ai te redirige a Listable para iniciar sesión y elegir los proyectos a los que la integración puede acceder. Revoca en cualquier momento desde la página de Claves API en tu panel de administración de Listable.

Claude Code

claude mcp add --transport http listable https://app.get-listable.com/api/v1/external/mcp

Claude Code realiza el flujo OAuth en tu navegador en el primer uso. Verifica con /mcp dentro de una sesión.

Cursor

En Configuración → MCP, añade un servidor HTTP:

Nombre: listable
URL: https://app.get-listable.com/api/v1/external/mcp

Cursor activará el flujo OAuth en la primera conexión.

Respaldo Stdio (este paquete npm)

Usa esta ruta para Claude Desktop (que aún no admite HTTP MCP) o cualquier cliente solo-stdio. Necesitarás crear una clave API primero:

Abre Claves API en tu panel de administración de Listable: https://app.get-listable.com/my-account/api-keys
Haz clic en Crear una nueva clave API, asígnale un nombre (por ejemplo, "Claude Desktop") y, opcionalmente, delimítala a proyectos específicos
Copia la clave: solo se muestra una vez

Claude Desktop

Abre Configuración → Desarrollador → Editar configuración (claude_desktop_config.json) y añade:

{
  "mcpServers": {
    "listable": {
      "command": "npx",
      "args": ["-y", "listable-mcp"],
      "env": {
        "LISTABLE_API_TOKEN": "lst_..."
      }
    }
  }
}

Cierra y reinicia Claude Desktop por completo. Las herramientas de Listable aparecen en el menú Buscar y herramientas.

Otros clientes stdio

Cualquier cliente MCP que inicie un subproceso puede ejecutar npx -y listable-mcp y pasar LISTABLE_API_TOKEN en el entorno.

Instalación global (opcional)

Si prefieres no depender de la resolución de npx en cada inicio:

npm install -g listable-mcp

Luego apunta el cliente al binario listable-mcp directamente en lugar de npx -y listable-mcp.

Configuración

Variable de entorno	Obligatoria	Predeterminado	Propósito
`LISTABLE_API_TOKEN`	sí	—	Clave API de https://app.get-listable.com/my-account/api-keys
`LISTABLE_MCP_URL`	no	`https://app.get-listable.com/api/v1/external/mcp`	Sobrescribir el endpoint ascendente (Listable autoalojado o staging)

Límites de velocidad

Plan Growth: 60 solicitudes/minuto, 750 llamadas de herramientas/mes
Plan Pro: 300 solicitudes/minuto, llamadas mensuales ilimitadas

Alcanzar cualquiera de los límites devuelve un 429 con retry_after (por minuto) o quota_reset_at (mensual). Para trabajo masivo, la IA prefiere bulk_create_items (hasta 100 listados/llamada) en lugar de muchas creaciones individuales.

Seguridad

Las descripciones de las herramientas le indican a la IA:

Descubrir primero — llamar a get_schema antes de editar para que los cambios usen los campos personalizados y tipos de bloque correctos
Confirmar operaciones destructivas — eliminaciones, reemplazos completos de bloques de página, cambios de estructura de URL y sobrescrituras de scripts solicitan confirmación explícita
Respaldar antes de editar — mantener el estado anterior en contexto para restaurarlo si algo sale mal
Añadir, no reemplazar — los scripts (analítica, seguimiento) se añaden al contenido existente

Cada llamada de herramienta se registra contra el proyecto que tocó. Consulta la línea de tiempo en Proyecto → API en tu panel de administración de Listable: filtrable por fuente (MCP vs REST) y conservada durante 30 días.

Revocación de acceso

Concesiones OAuth: aparecen en la página de Claves API junto con las claves creadas manualmente. Revócalas allí.
Claves API estáticas: revócalas desde la misma página de Claves API. El cliente de IA recibirá errores 401 en su próxima llamada.

Solución de problemas

Errores de "No autenticado" (shim stdio) — Confirma que LISTABLE_API_TOKEN esté configurado en la misma shell o bloque de configuración que inicia el cliente. En Claude Desktop, el mapa env en la configuración JSON debe contener la clave.

Bucle OAuth / el navegador no redirige de vuelta — Asegúrate de que la URL de redirección del cliente sea accesible. Algunos clientes usan una devolución de llamada en localhost; las cookies o los bloqueadores de ventanas emergentes pueden interrumpir el flujo.

"Herramienta no disponible" — Reinicia el cliente (Claude Desktop requiere un cierre y reapertura completos). En Claude Code, ejecuta /mcp para confirmar que Listable está conectado.

403 en proyectos específicos — Tu token está delimitado. OAuth: vuelve a ejecutar la aprobación y selecciona más proyectos. Clave estática: crea una nueva sin delimitación de proyectos.

Enlaces

Listable: https://get-listable.com
Documentación de API + MCP: https://app.get-listable.com/my-account/api-docs
Model Context Protocol: https://modelcontextprotocol.io

Licencia

MIT — consulta LICENSE.