Pixapi MCP

Genera imágenes y videos desde agentes de IA: consulta el precio de créditos en vivo y el saldo, inicia tareas asíncronas de imagen o video, y obtén resultados a través de MCP.

GitHub

Documentación

pixapi-mcp

Utiliza las herramientas de generación de imágenes y videos de Pixapi desde clientes MCP.

  • Sitio web: Pixapi
  • Endpoint MCP remoto: https://api.pixapi.ai/mcp
  • Licencia: MIT

Inicio rápido

Configura tu proyecto automáticamente (Node.js 22+):

npx -y pixapi-mcp init --client codex

Reemplaza codex con tu cliente, o usa --client all para los cinco:

Cliente--clientArchivo de configuración
Claude Codeclaude-code.mcp.json
Cursorcursor.cursor/mcp.json
Codexcodex.codex/config.toml
VS Code / GitHub Copilotvscode.vscode/mcp.json
Gemini CLIgemini-cli.gemini/settings.json

Sin --client, el valor predeterminado es Claude Code y Cursor (--client both). Usa --project /path/to/project para configurar otro proyecto.

Recarga tu cliente MCP y conéctate a pixapi. Completa el inicio de sesión en el navegador y la solicitud de autorización la primera vez. El cliente guarda la sesión OAuth y la renueva automáticamente; no se requiere editar claves API ni credenciales. El cliente puede pedirte que inicies sesión nuevamente si la autorización se revoca o expira. Cada cliente gestiona su propia sesión OAuth nativa.

init configura una conexión HTTP remota directa de forma predeterminada. Si tu cliente tiene una interfaz para agregar servidores MCP, también puedes ingresar la URL del endpoint allí sin instalar este paquete npm ni Node.js.

Codex requiere un proyecto de confianza. En VS Code, usa MCP: List Servers para iniciar pixapi; en Gemini CLI, usa /mcp para inspeccionarlo. Completa cualquier solicitud de confianza o inicio de sesión del cliente. init no cambia las políticas de seguridad del cliente.

Configuración generada

Claude Code:

{"mcpServers":{"pixapi":{"type":"http","url":"https://api.pixapi.ai/mcp"}}}

Cursor usa la misma entrada mcpServers con url y sin campo type. VS Code usa servers con type: "http" y url. Gemini CLI usa mcpServers con httpUrl.

Codex:

[mcp_servers.pixapi]
url = "https://api.pixapi.ai/mcp"

Ejecutar init actualiza la entrada pixapi y conserva otros servidores y configuraciones. Los comentarios JSONC de VS Code se conservan. La configuración TOML de Codex se conserva, pero los comentarios y el formato no. Todas las configuraciones seleccionadas se analizan antes de escribir; una falla del sistema de archivos durante las escrituras puede dejar algunos archivos sin actualizar. Corrige el problema local y vuelve a ejecutar init.

Puente stdio local

Para clientes que necesitan stdio, configura el puente explícitamente:

npx -y pixapi-mcp init --client cursor --transport stdio

La entrada generada ejecuta npx -y pixapi-mcp proxy sin credenciales. Las instalaciones del paquete npm desde el registro también inician el puente directamente: no se requiere un comando init separado ni una variable de entorno.

El puente completa el protocolo de enlace MCP local inmediatamente. En la primera solicitud de herramienta, abre la autorización del navegador y luego reenvía las herramientas a Pixapi. Las conexiones posteriores reutilizan la sesión guardada y renuevan los tokens automáticamente. Para clientes con un tiempo de espera corto en el descubrimiento de herramientas, inicia sesión una vez de antemano:

npx -y pixapi-mcp login

Si un cliente agota el tiempo de espera durante el inicio de sesión inicial en el navegador, completa el inicio de sesión y vuelve a conectar el cliente. No se imprime ninguna URL de autorización, código o token en la salida estándar o de error de MCP.

Las sesiones OAuth se almacenan por endpoint en ~/.pixapi/oauth-<hash>.json. En macOS y Linux, el directorio usa el modo 0700 y los archivos usan 0600. Las escrituras son atómicas; los procesos del puente concurrentes comparten un bloqueo de autorización. Los verificadores PKCE y el estado de devolución de llamada se mantienen solo en memoria. La devolución de llamada se vincula a loopback en el mismo host que el puente. Para un host sin interfaz gráfica o remoto, prefiere la conexión OAuth remota nativa del cliente.

Instalaciones existentes con clave API

Las configuraciones existentes con clave API siguen siendo compatibles. Para una instalación explícita con clave API, establece PIXAPI_API_KEY al ejecutar init; esto configura stdio y guarda la clave de forma privada en ~/.pixapi/mcp-credentials.json. Un --transport remote explícito siempre selecciona OAuth nativo, incluso si esa variable está establecida. El proxy también acepta PIXAPI_API_KEY directamente para implementaciones sin supervisión.

El proxy da prioridad a una clave de entorno explícita, luego a una sesión OAuth guardada y luego a un archivo de clave heredado. Para migrar un puente existente a OAuth, ejecuta pixapi-mcp login y elimina cualquier anulación de PIXAPI_API_KEY de su entorno. Las claves y los tokens nunca aparecen en las configuraciones de proyecto generadas.

Herramientas disponibles

Este paquete reenvía la lista de herramientas en vivo desde el endpoint remoto de Pixapi MCP. Después de conectarte, llama a tools/list o pixapi_get_pricing_and_balance para obtener el catálogo actual.

pixapi_get_pricing_and_balance

Devuelve tu saldo actual y los precios en vivo de modelos de imágenes/videos. Cada fila del catálogo incluye un type:

  • Imágenes: text_to_image, image_to_image
  • Videos: text_to_video, image_to_video

Las filas marcadas con mcp_generate_supported=true se pueden llamar mediante la herramienta de generación correspondiente.

pixapi_generate_image

Inicia una tarea de imagen asíncrona y devuelve un task_id. Usa type=text_to_image para una solicitud solo con indicación, o type=image_to_image con el campo image. La herramienta acepta los modelos de imagen del catálogo en vivo, incluidos Gemini, GPT Image, Flux, Seedream, Qwen y Wan.

Esta llamada consume créditos de la cuenta. No es idempotente: repetir la misma llamada crea otra tarea y puede volver a cobrar a la cuenta.

pixapi_generate_video

Inicia una tarea de video asíncrona y devuelve un task_id. Usa type=text_to_video para una solicitud solo con indicación, o type=image_to_video con el campo image. Pasa seconds y resolution según lo requiera el modelo seleccionado.

Esta llamada consume créditos de la cuenta y no es idempotente.

pixapi_get_task

Recupera una tarea de imagen o video propiedad de la cuenta autenticada. Consulta esta herramienta con el task_id devuelto hasta que el estado sea completed o failed. Una tarea completada incluye URL de medios.

Flujo de agente recomendado:

  1. Llama a pixapi_get_pricing_and_balance.
  2. Selecciona una fila del catálogo con mcp_generate_supported=true y verifica el saldo.
  3. Llama a pixapi_generate_image o pixapi_generate_video una vez y conserva su task_id.
  4. Consulta pixapi_get_task cada pocos segundos.
  5. Devuelve la URL del resultado cuando la tarea esté completa.

Referencia de CLI

pixapi-mcp init [--client <name|all|both>] [--project <path>] [--transport <remote|stdio>]
pixapi-mcp login
pixapi-mcp proxy
pixapi-mcp --help

Sin argumentos, el paquete inicia el proxy stdio.

Solución de problemas

  • Las herramientas no aparecen: recarga el cliente, habilita el servidor pixapi y completa la confianza del proyecto y el inicio de sesión en el navegador. Para stdio, asegúrate de que Node.js 22+ y npx estén disponibles en el host que ejecuta el puente.
  • Autorización denegada o agotada: reintenta el inicio de sesión desde el cliente nativo, o ejecuta pixapi-mcp login para el puente y completa la autorización del navegador.
  • Puerto de devolución de llamada no disponible: cierra otro inicio de sesión pendiente de Pixapi y reintenta.
  • Servicio no disponible: verifica tu conexión y reintenta más tarde. Las respuestas HTTP internas y los detalles de excepciones se omiten de los errores públicos.
  • Clave API heredada no válida: reemplaza la clave o migra a OAuth como se indicó anteriormente.

Seguridad y limitaciones actuales

  • No confirmes ni compartas archivos en ~/.pixapi/.
  • Revoca credenciales no utilizadas o expuestas en tu cuenta de Pixapi.
  • El puente stdio solo reenvía herramientas. Los recursos, indicaciones, muestreo y elicitación no están expuestos por este paquete.
  • La generación de imágenes y videos es asíncrona y no idempotente. El puente reintenta el rechazo de autenticación HTTP una vez; no reintenta fallos de red ni errores de servidor que puedan haber ocurrido después de ejecutar una herramienta.
  • La recarga de la cuenta no está expuesta como herramienta MCP; completa el pago en Pixapi.

Para documentación del servicio, visita Documentación de Pixapi.

Registro MCP oficial

Este servidor está publicado en el Registro MCP oficial como io.github.Pixapi-AI/pixapi-mcp, con ambos métodos de conexión declarados en server.json: el endpoint remoto y el paquete npm. Ambos admiten OAuth sin una clave API requerida a partir de la versión 0.1.4.

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.Pixapi-AI/pixapi-mcp"

Establece versiones coincidentes en package.json, package-lock.json y server.json antes de enviar la etiqueta v* correspondiente. El flujo de trabajo de lanzamiento instala dependencias bloqueadas, ejecuta verificaciones y valida el manifiesto del Registro antes de publicar. Las ejecuciones manuales también deben seleccionar esa etiqueta de lanzamiento. Una nueva ejecución compara la integridad del paquete npm existente y los metadatos del Registro, y solo publica los pasos faltantes; los contenidos conflictivos requieren una nueva versión. La autenticación del Registro usa GitHub OIDC, sin un token de Registro almacenado.