Servidor local y MCP

1. Arranca y conecta

MCP conecta el chat con herramientas del equipo y servicios externos. Necesitas el servidor local de ZeroChat. Elige una forma de instalación:

PyPI (recomendado)

Linux, macOS y Android (Termux):

pip install zerochat
zerochat

Windows (PowerShell o CMD): usa el lanzador py, que funciona aunque la carpeta Scripts de Python no esté en el PATH.

py -m pip install zerochat
py -m zerochat

Descarga directa

Linux, macOS y Android (Termux):

curl -fsSL https://albalday.github.io/zerochat/zerochat.py -o zerochat.py
python3 zerochat.py

Windows (PowerShell o CMD): curl.exe viene con Windows 10 y 11; en PowerShell hay que escribirlo con .exe para no usar el alias de Invoke-WebRequest.

curl.exe -fsSL https://albalday.github.io/zerochat/zerochat.py -o zerochat.py
py zerochat.py

Para los siguientes arranques, utiliza zerochat (o py -m zerochat en Windows) o python3 zerochat.py (py zerochat.py en Windows), respectivamente. Ambos abren GitHub Pages y guardan los datos locales en ~/zerochat/.

1. Mantén el servidor en ejecución y abre el enlace que proporciona.
2. Ve a Ajustes → MCP y comprueba la conexión y las herramientas descubiertas.
3. Habilita las herramientas que necesites y revisa sus permisos.

El enlace con que zerochat abre el navegador lleva el token del día; la página lo guarda y vuelve a conectar sola en los siguientes arranques. Si aparece desconectado, comprueba que el proceso siga en ejecución y revisa los permisos de red local del navegador. Para un servidor en otro puerto, en otro equipo (por un túnel SSH) o detrás de un proxy inverso, usa el panel de Conexión (el icono del enchufe, junto a la rueda de configuración de la barra lateral): desactiva Conexión local, escribe su URL y pulsa Conectar. Si falta el token o ha caducado (cambia cada día), la página pide el usuario y la contraseña de la cuenta que ejecuta zerochat; la contraseña no se guarda. No compartas el enlace de arranque.

Modos de uso, datos locales y actualizaciones →

2. Usa las herramientas del equipo

• Archivos: list_directory, read_file, write_file, edit_file y search_files.
• Comandos: run_command ejecuta cada comando en una shell nueva que arranca en el directorio del proyecto: un cd, un export o un entorno virtual activado no pasan a la llamada siguiente, así que el modelo los encadena con && en el mismo comando. La salida une stdout y stderr en el orden en que se producen. Por defecto espera hasta 30 segundos (el modelo puede pedir hasta 10 minutos) y, si el comando no ha terminado, lo detiene junto con los procesos que haya lanzado. Para servidores, vigilantes de cambios o tareas largas, el modelo lo lanza en segundo plano y lo sigue o lo detiene con check_command. Si un comando en segundo plano termina sin que el modelo lo haya consultado, en tu siguiente mensaje se le indica cómo acabó, con sus últimas líneas; esa nota no aparece en el chat. Cada comando aparece en el chat como una tarjeta con su estado y su duración (en ejecución, en segundo plano, terminado, código de error, plazo agotado o detenido). Al desplegarla muestra el log del comando, que se sigue actualizando mientras está en marcha, y Detener lo termina. Si al terminar una respuesta quedan comandos en segundo plano en marcha, se añade al final del chat un aviso plegado; al desplegarlo los enumera con el tiempo que llevaban, y cada uno lleva a su tarjeta. El aviso no se actualiza: el estado de cada comando está en su tarjeta. Si cerrar la pestaña va a detener ZeroChat, el navegador pide confirmación mientras haya comandos en marcha. Al pulsar Detener en el chat se detienen también los comandos que el turno estaba esperando, y al cerrar ZeroChat se detienen todos. Si ZeroChat termina de golpe, Windows los detiene en el acto; en Linux, macOS y Android se detienen la próxima vez que arranca. En Linux/macOS/Android utiliza bash/sh; en Windows, PowerShell.
• Comprobaciones de sintaxis: get_diagnostics; no sustituye las pruebas del proyecto.
• Navegador: browser_action requiere Node.js y disponer de Chrome o Edge en el sistema (o Chromium). Para usarla, inicia el servicio Playwright en Ajustes → MCP (se instala solo) y elígela en Ajustes › Navegador. Consulta la ayuda del navegador.

Los resultados de herramientas forman parte de la conversación y pueden enviarse al modelo seleccionado.

3. Inicia un servicio MCP externo

En Ajustes → MCP → Servidores MCP disponibles, configura cada servicio y pulsa Iniciar. ZeroChat prepara sus dependencias declaradas. Para detenerlo, pulsa Detener.

winget install OpenJS.NodeJS.LTS

Arranque y OAuth

El botón muestra Iniciando y queda deshabilitado. Si el arranque supera 15 segundos, ZeroChat consulta el estado y espera en intervalos de 15 segundos: hasta 20 minutos mientras instala dependencias (por ejemplo, Playwright y su navegador) o espera la autorización OAuth, y hasta diez intervalos más mientras inicia. La instalación y la espera de OAuth no se consideran fallos al vencer el primer timeout; cuando el servicio está activo, el panel se actualiza automáticamente. El botón indica el número de intento.

Si el servicio necesita OAuth, la tarjeta muestra el aviso Se requiere autorización con el botón Autorizar en el navegador. ZeroChat intenta abrir la pestaña de autorización; si el navegador la bloquea, pulsa el botón. Al abrirse desde la propia web, funciona también en Android y Termux. Si se agota la espera, el servicio puede seguir arrancando; recarga la página para comprobar el resultado.

Los servicios no se reinician automáticamente en el siguiente arranque de ZeroChat. Si había alguno activo en la sesión anterior, al conectar aparece un diálogo con la lista: quita con la X los que no quieras y pulsa Iniciar para arrancar el resto, o No iniciar para dejarlos detenidos. Los que no se inician quedan como no iniciados y no se vuelven a ofrecer. Si alguno falla, ZeroChat lo indica y el error queda en su tarjeta de este panel.

Las acciones de este panel se aplican al momento: no necesitan Guardar.

Si falla la instalación

Lee el error de la tarjeta. Comprueba node --version, npm --version, la conexión a la red y el espacio libre; después vuelve a intentarlo. No necesitas reinstalar ZeroChat. En Windows, consulta Instalar Node.js en Windows.

4. Revisa los permisos

En Ajustes → Permisos, elige la política global y revisa las autorizaciones guardadas. En el panel MCP puedes elegir Preguntar, Permitir o Denegar para cada herramienta.

• Pedir autorización: pregunta cuando las reglas existentes no resuelven la llamada.
• Confiar en el espacio de trabajo: además de las reglas de directorio, permite archivos con rutas relativas dentro del proyecto y comandos simples: sin encadenar (;, &&, $()), sin redirigir a archivos, sin rutas absolutas, ~, variables ni .., y con tuberías solo hacia filtros como head, grep o wc. El resto pide confirmación. No es un aislamiento: un comando simple como python3 script.py actúa con tus permisos.
• Todo autorizado: ejecuta sin confirmación, salvo bloqueos explícitos que tengan prioridad.

Las decisiones pueden aplicarse a una llamada, a la sesión del backend o de forma permanente. Las herramientas externas se llaman <servicio>_<herramienta>: confiar en composio autoriza sus herramientas, no las de otros servicios. Permitir una herramienta no autoriza todo el servicio.

Directorios permitidos: una regla por línea con R: (lectura), W: (escritura) o RW: (ambas). Usa * para un segmento y ** para subdirectorios. Una lista vacía incorpora una regla de lectura para el directorio de arranque. Las rutas con ~ o variables no se resuelven en el navegador y siempre piden confirmación: usa rutas absolutas. Los comandos también tienen reglas de prefijos y comprobaciones adicionales.

Permitir siempre un comando: autoriza solo ese programa, sin encadenamiento, tuberías ni redirecciones a archivos. Un cd <carpeta> && inicial se admite si la carpeta está cubierta por una regla de directorio, igual que el directorio de trabajo del comando. Autorizar un programa confía en todas sus opciones: git puede ejecutar otros comandos mediante su configuración o alias.

Estas reglas no son un aislamiento del sistema operativo. Los comandos y servicios autorizados actúan con los permisos del proceso local. Detener una llamada no revierte sus cambios.

5. Añade tu propio servicio

Crea una carpeta nueva dentro de ~/zerochat/services/ con nombre e id únicos. Usa ejemplo como plantilla: service.json es obligatorio; añade installer.json solo para paquetes npm. El README.md de la plantilla describe los campos, incluido el enlace opcional help.

Puedes pedir al agente que cree la definición con uno de estos prompts. Sustituye los marcadores. El agente prepara los archivos; tú introduces las credenciales y arrancas el servicio.

Quiero crear el MCP local <nombre-del-mcp> para ZeroChat.
Localiza el directorio personal del usuario y lee README.md,
service.json e installer.json.example de zerochat/services/ejemplo
usando sus rutas absolutas. Sigue las instrucciones del README.
Consulta la documentación oficial del MCP y crea una carpeta hermana
con nombre e id propios; no modifiques los servicios incluidos.
Si necesita una API key, deja PASTE_API_KEY_HERE en service.json,
dentro del objeto env de launch, con la variable que exige el MCP.
Yo sustituiré el marcador por mi clave a mano en ese service.json.
No me pidas la clave ni crees un archivo launch.env o .env.
Indica la ruta absoluta del JSON y el campo que debo editar a mano.
No instales ni inicies el servicio; lo haré desde Ajustes → MCP.

Quiero crear el MCP remoto <nombre-del-mcp> para ZeroChat.
Su endpoint es <url-del-mcp>.
Localiza el directorio personal del usuario y lee README.md de
zerochat/services/ejemplo y los JSON de zerochat/services/composio
usando sus rutas absolutas. Sigue el README y toma Composio
como ejemplo de un puente mcp-remote gestionado por stdio.
Crea una carpeta hermana con nombre e id propios y textos bilingües.
Consulta la documentación oficial del MCP y del puente para adaptar
endpoint, transporte y autenticación. No copies sin verificar las
opciones específicas de OAuth o protocolo de Composio.
Conserva el aislamiento HOME y USERPROFILE en ${serviceDir}.
Si requiere API key, deja PASTE_API_KEY_HERE en service.json,
dentro del objeto env de launch. Yo introduciré mi clave a mano
en ese service.json; no crees un archivo launch.env o .env.
Configura --header con la cabecera que exige el proveedor y una
referencia a esa variable; mcp-remote resolverá la referencia.
No me pidas la clave ni la escribas en los argumentos o en la URL.
Indica la ruta absoluta del JSON y el campo que debo editar a mano.
No instales ni inicies el servicio; lo haré desde Ajustes → MCP.

Si la carpeta nueva no aparece en Ajustes → MCP, reinicia ZeroChat y vuelve a conectar. Tus carpetas se conservan al actualizar. Las definiciones incluidas (ejemplo, composio, playwright, memory) se restauran al arrancar; crea una copia con otro nombre e id en lugar de editarlas. No copies dependencias ni credenciales OAuth.

6. Introduce una API key

launch.env indica el objeto env dentro de launch en service.json; no es un archivo. El agente deja el marcador y tú introduces la clave real a mano en ese JSON.

1. Detén el servicio si está activo. Abre el service.json de tu carpeta.
2. Sustituye PASTE_API_KEY_HERE en launch.env por la clave real, usando el nombre de variable que exige el proveedor. No la pegues en el chat.
3. Guarda un JSON válido. En Linux o Termux limita el acceso con chmod 600 /ruta/absoluta/zerochat/services/mi-servicio/service.json.
4. Inicia el servicio desde Ajustes → MCP.

La clave queda en texto plano: no compartas ni subas este archivo al repositorio. Borrar ~/zerochat/ también elimina los servicios y sus credenciales; conserva una copia privada si la necesitas.

"env": {
  "SERVICE_API_KEY": "PASTE_API_KEY_HERE"
}

"args": [
  "${serviceDir}/node_modules/mcp-remote/dist/proxy.js",
  "https://mcp.example.com/mcp",
  "--header",
  "Authorization: Bearer ${REMOTE_API_KEY}"
],
"env": {
  "HOME": "${serviceDir}",
  "USERPROFILE": "${serviceDir}",
  "REMOTE_API_KEY": "PASTE_API_KEY_HERE"
}