@mockzilla/mcp

Servidor MCP para mockzilla. Permite a agentes como Claude Desktop y Cursor controlar mockzilla en nombre del usuario, y les permite ayudar a los usuarios a probar mockzilla sin necesidad de una cuenta primero.

El puente expone dos planos de herramientas:

• Plano local (sin cuenta): comprueba si la CLI de mockzilla está instalada, la instala para el usuario (binario precompilado, go install o go run), echa un vistazo a una especificación OpenAPI y ejecuta servidores mock portátiles localmente. Nada sale de la máquina del usuario.

• Plano alojado (con cuenta): se redirige al endpoint MCP de mockzilla.org cuando se establece MOCKZILLA_TOKEN. Lista simulaciones, despliega paquetes del catálogo, etc.

Sin un token, el plano local es toda la superficie: los agentes aún pueden ayudar a los usuarios a explorar mockzilla antes de registrarse.

Instalación

Claude Code

Comando de una línea, sin editar configuración:

claude mcp add -s user mockzilla -- npx -y @mockzilla/mcp@latest

-s user lo instala para tu cuenta de usuario (disponible en cada proyecto). Elimina -s user para limitar el alcance solo al proyecto actual.

Claude Desktop

Edita ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mockzilla": {
      "command": "npx",
      "args": ["-y", "@mockzilla/mcp@latest"]
    }
  }
}

Cursor

Lo más fácil: Cursor Settings → MCP Servers → Add new MCP server, rellena:

• Nombre: mockzilla

• Comando: npx

• Argumentos: -y @mockzilla/mcp@latest

O edita ~/.cursor/mcp.json directamente:

{
  "mcpServers": {
    "mockzilla": {
      "command": "npx",
      "args": ["-y", "@mockzilla/mcp@latest"]
    }
  }
}

Gemini CLI

Comando de una línea, sin editar configuración:

gemini mcp add -s user mockzilla npx -y @mockzilla/mcp@latest

-s user escribe en ~/.gemini/settings.json (disponible en cada proyecto). Elimina -s user (o usa -s project) para limitar el alcance al archivo .gemini/settings.json del directorio actual.

O edita el archivo de configuración directamente:

{
  "mcpServers": {
    "mockzilla": {
      "command": "npx",
      "args": ["-y", "@mockzilla/mcp@latest"]
    }
  }
}

Reinicia el cliente después de editar la configuración.

¿Por qué @latest? Sin esto, npx almacena en caché la primera versión resuelta y no detectará nuevas publicaciones. Fijar en @latest hace que npx vuelva a comprobar el registro en cada inicio, por lo que un reinicio de Claude Desktop / Cursor es suficiente para actualizar. Compensación: ~200ms de inicio adicional.

Qué puedes preguntar

Sin un token (plano local):

• "¿Está instalada la CLI de mockzilla?"

• "Instala mockzilla por mí." (el agente preguntará: descargar / go-install / go-run)

• "Levanta la especificación petstore localmente para que pueda hacerle curl."

• "¿Qué endpoints tiene https://example.com/openapi.yaml?"

• "Detén el mock que iniciaste."

Con un token (plano alojado añadido):

• "Lista las simulaciones que he desplegado."

• "Muéstrame los productos del catálogo."

• "Despliega un sandbox de Stripe llamado stripe-test y espera a la URL en vivo."

• "Crea un mock desde esta URL de OpenAPI en mockzilla."

Herramientas

Local

Alojado

Disponible cuando se establece MOCKZILLA_TOKEN. Reenviado a mockzilla.org. Consulta la documentación del servidor alojado para ver la lista de herramientas en vivo; en el momento de escribir esto incluye get_context, list_sims, list_catalog_products, deploy_mock_from_{catalog,spec,url} y wait_for_deploy.

Configuración

Caché

El puente mantiene todo bajo ~/.cache/mockzilla-mcp/:

~/.cache/mockzilla-mcp/
├── bin/mockzilla        # downloaded or go-installed binary
├── config.json          # {method, version, invocation?}
└── mocks/               # mock_endpoint persists static endpoints here
    └── static/
        └── <service>/<path>/<method>/index.<ext>

rm -rf ~/.cache/mockzilla-mcp restablece el puente por completo (binario + todos los endpoints mokeados). Para borrar solo los mocks: rm -rf ~/.cache/mockzilla-mcp/mocks. El PATH del sistema nunca se toca, por lo que el restablecimiento no afecta a una instalación separada de brew.

Actualizaciones

El puente se envía con frecuencia; forma recomendada de mantenerse al día:

1. Fija @mockzilla/mcp@latest en la configuración de tu cliente MCP (ver fragmentos de instalación arriba) para que npx vuelva a comprobar el registro en cada inicio.

2. Reinicia Claude Desktop / Cursor periódicamente: es cuando se obtiene la nueva versión.

3. Si algo falla, pregúntale al agente: "Ejecuta bridge_status y dime si mockzilla-mcp está actualizado." Si está obsoleto, ejecuta npx clear-npx-cache @mockzilla/mcp y reinicia tu cliente.

La versión de la CLI de mockzilla está fijada por el puente (MOCKZILLA_VERSION en lib/install.js). Actualizar el puente actualiza la versión fijada; la siguiente llamada a install_cli actualiza la propia CLI.

Desarrollo

Consulta CLAUDE.md para conocer las convenciones del proyecto y un tutorial sobre cómo añadir una nueva herramienta.

Licencia

MIT.