Usa esta página para diagnosticar problemas habituales al configurar o utilizar el servidor MCP de Octoparse.
Problemas de autenticación
Clave de API ausente o no válida
Puede aparecer un error de autenticación si el servidor MCP no encuentra una clave de API de Octoparse válida.
Síntomas habituales:
Comprueba que la clave de API sea válida y que no se haya eliminado o regenerado.
Si utilizas una variable de entorno, confirma que esté disponible en el mismo shell o entorno de ejecución que inicia el servidor MCP.
Si no aparece ningún valor, vuelve a definir la clave antes de iniciar el servidor.
No incluyas claves de API en Git, scripts, capturas de pantalla, registros compartidos ni informes de incidencias públicos.
La clave funciona en un terminal, pero no en el cliente MCP
Algunos clientes MCP no heredan las variables de entorno del terminal interactivo.
Si el servidor funciona al iniciarlo manualmente, pero falla dentro de un cliente MCP, revisa la configuración del cliente y asegúrate de que la clave de API se pase al proceso del servidor.
Reinicia el cliente MCP después de actualizar las variables de entorno.
Problemas al iniciar el servidor
El servidor MCP no se inicia
Si el servidor no se inicia, comprueba el comando, el directorio de trabajo, la versión de Node.js y las variables de entorno.
Ejecuta primero el comando del servidor directamente en un terminal. Así podrás distinguir los problemas de configuración del cliente MCP de los problemas del entorno de ejecución del servidor.
Asegúrate de que el comando utilizado por el cliente MCP coincida con el que funciona en el terminal.
Comando no encontrado
Si el cliente indica que no encuentra el comando del servidor, utiliza una ruta absoluta o confirma que el paquete esté instalado.
Un comando puede funcionar en el shell y fallar en el cliente MCP si ambos no utilizan el mismo PATH.
Problemas de acceso a tareas
Tarea no encontrada
Puede aparecer este error si el ID de la tarea es incorrecto o si la cuenta autenticada no tiene acceso a ella.
Comprueba lo siguiente:
- El ID de la tarea se ha copiado correctamente.
- La tarea pertenece a la cuenta autenticada de Octoparse.
- La tarea no se ha eliminado.
- La clave de API pertenece al espacio de trabajo o a la cuenta correctos.
No se devuelve ninguna tarea accesible
Si la búsqueda no devuelve resultados, verifica primero la clave de API y el acceso de la cuenta. Después, prueba una consulta más amplia o enumera las tareas sin filtrar por palabra clave.
Problemas de ejecución
La tarea no se inicia
Una tarea puede no iniciarse si su definición no es compatible, si ya se está ejecutando o si la cuenta no tiene permiso para ejecutarla.
Comprueba primero la tarea en Octoparse y vuelve a intentarlo desde el cliente MCP.
Si se creó con un flujo antiguo, vuelve a crearla o actualízala en la aplicación actual de Octoparse antes de ejecutarla mediante automatización.
La ejecución se inicia, pero no devuelve datos
Si la ejecución finaliza correctamente, pero la exportación no devuelve datos, comprueba si la tarea ha terminado y si la ejecución o el lote seleccionados contienen datos.
Causas habituales:
- La tarea todavía se está ejecutando.
- El ID de lote seleccionado no contiene datos.
- La tarea finalizó, pero no encontró registros.
- Se solicitó la exportación antes de que terminara la ejecución.
Problemas de exportación
La exportación falla
Verifica que la tarea haya finalizado y que la herramienta admita el formato de exportación elegido.
Si el comando o la herramienta acepta un ID de lote, asegúrate de que pertenezca a la misma tarea y al mismo historial de ejecución.
Archivo de exportación vacío
Normalmente significa que la ejecución seleccionada no contiene registros extraídos o que se solicitó la exportación antes de finalizar la extracción.
Comprueba primero el historial y vuelve a exportar con la ejecución o el lote correctos.
Límites de solicitudes y fallos transitorios
Si una solicitud falla de manera intermitente, espera brevemente y vuelve a intentarlo. Los problemas de red, los retrasos de la cola de tareas o los errores temporales del backend pueden provocar fallos transitorios.
Si el fallo se repite, recopila:
- El nombre y la versión del cliente MCP
- La versión del servidor MCP
- La llamada a la herramienta o el prompt exactos
- El ID de la tarea
- El mensaje de error
- Si la misma tarea funciona directamente en Octoparse
Elimina claves de API, tokens de acceso, cookies y datos personales antes de compartir registros.
- Nombre del cliente MCP
- Versión del servidor MCP
- Sistema operativo
- Versión de Node.js
- Nombre de la herramienta que falló
- Mensaje de error exacto
- ID de la tarea o un ejemplo anonimizado
- Si la tarea funciona en Octoparse fuera de MCP
