claudeaibridge

Dale a claude.ai — incluido el plan gratuito — una experiencia real de agente de codificación en tu propia máquina: edición de archivos, acceso al shell, git, todo en una carpeta de proyecto que elijas explícitamente, y controlado desde el web. Sin IDE, sin suscripción a Claude Code, sin copiar y pegar manualmente código en el navegador.

Funciona ejecutando un pequeño servidor local que habla MCP (el mismo protocolo que Claude Code y Claude Desktop usan para las herramientas), exponiéndolo a claude.ai como un conector personalizado a través de una URL pública (mediante ngrok, o tu propio dominio/túnel), y limitando el acceso con una pantalla real de consentimiento OAuth que solo tú puedes aprobar, en esta máquina.

Por qué

Los conectores de claude.ai ya permiten a Claude leer/escribir datos en otros servicios (Google Drive, GitHub, etc.) a través de servidores MCP remotos. Este proyecto es ese mismo mecanismo apuntando a tu propio sistema de archivos: lo que Claude Code hace a nivel local, accesible desde una pestaña del navegador.

Related MCP server: claude-agent-mcp

Cómo se mantiene a salvo

Esto le da a una página web la capacidad de editar archivos y ejecutar comandos shell en tu máquina. El diseño se apoya más en la contención que en la confianza:

• Tú eliges las carpetas. El conector solo puede ver las carpetas de proyecto que hayas registrado explícitamente en esta máquina (mediante la CLI): no tiene forma de añadir una nueva por su cuenta, así que una URL de conector filtrada no significa "acceso a todo tu disco".

• Contención del sistema de archivos. Cada herramienta de archivos resuelve y comprueba las rutas contra la raíz del proyecto activo antes de tocar el disco; se rechazan los recorridos con ../ y las fugas de symlinks. Los comandos shell se ejecutan dentro de un sandbox (bwrap en Linux, sandbox-exec en macOS) que hace que el resto del sistema de archivos sea de solo lectura.

• Consentimiento OAuth real. Conectarse no es un trámite automático: claude.ai tiene que completar un flujo OAuth que abre una página en esta máquina, enumerando exactamente qué proyectos están registrados, y un humano debe hacer clic en Aprobar. Nada se otorga en silencio.

• Seguridad para deshacer. Las ediciones de archivos guardan una copia de seguridad antes de cambiar nada; los borrados mueven los archivos a una papelera local en su lugar de eliminarlos, ambas dentro de la carpeta .claudeaibridge/ del proyecto.

• Ún registro de auditoría. Cada acción de archivo/shell se añade a <project>/.claudeaibridge/audit.log en texto plano, y siempre puedes preguntar: "¿qué hizo realmente Claude aquí?"

Widgets interactivos

En los hosts que lo admiten, file_write y file_edit muestran su cambio como un diff coloreado línea a línea, en el propio chat, automáticamente y sin ningún añadido. Está abierto por defecto; haz clic en el nombre del archivo para plegarlo o desplegarlo. Claude sigue recibiendo exactamente los mismos datos de resultado en cualquier caso (qué cambió, ruta de copia de seguridad, detalles del error); el widget es una interpretación de esos mismos datos, no un sustituto. En un host sin soporte de widgets, el resultado simple de la herramienta no se ve afectado.

Compatibilidad de plataformas

Linux y macOS. Windows todavía no es compatible (el enfoque de sandbox no tiene equivalente implementado en Windows).

Instalación

Opción 1 — binario precompilado. Genera uno tú mismo con PyInstaller (consulta Compilación desde el software): no hay una descarga aparte, solo un paso de construcción.

Opción 2 — desde el código fuente, con Python 3.10+:

git clone https://github.com/yemi-sh/claudeaibridge.git
cd claudeaibridge
python3 -m venv .venv
.venv/bin/pip install -e .

Inicio rápido

claudeaibridge init

Esto te guía por todo el proceso:

1. Un ngrok authtoken (aafe — consigue uno aquí), o tu propio dominio/túnel si ya tienes uno, o solo local para pruebas.

2. Elegir las carpetas de proyecto en las que claude.ai debería poder trabajar, mediante un navegador interactivo (flechas para navegar, Espacio para seleccionar, escribir para buscar).

3. Instalarse a sí mismo como servicio en segundo plano (systemd en Linux, launchd en macOS) e imprimir la URL del conector: puede cerrar la terminal, y el servicio sigue ejecutándose.

Después, en claude.ai: Ajustes → Conectores → Añadir conector personalizado, pega la URL impresa. claude.ai abrirá una pestaña en el navegador para autorizarción; haz clic en Aceptar la autorización — y estás conectado. Pide a Claude que liste los proyectos disponibles, selecciona uno y empieza a trabajar.

Puedes consultarlo en cualquier momento con claudeaibridge status. If no hay ningún gestor de servicios disponible (Windows, o una configuración Linux sin sesión de usuario systemd), init vuelve a ejecutarse en el terminal en primer plano.

Referencia de comandos

claudeaibridge init

El asistente de instalación interactivo descrito arriba. Es seguro repetirlo: cada paso te indica lo que ya está configurado y te permite mantenerlo o cambiarlo. Al repetirlo, se reinstala el servicio en segundo plano con lo que elijas esta vez, reemplazando el anterior.

claudeaibridge status

Indica si el servicio en segundo plano está en ejecución y la última URL del conector que imprimió.

claudeaibridge stop

Detiene el servicio en segundo plano y lo desinstala (elimina la unidad de systemd/launchd por completo, no solo lo detiene) — el robot se pone desconectado hasta que vuelvas a ejecutar init o serve.

Proyectos

claudeaibridge add-project ~/code/my-repo   # register a specific folder
claudeaibridge add-project                  # or pick one (or several) interactively
claudeaibridge edit-project ~/code/my-repo  # unregister that folder directly
claudeaibridge edit-project                 # or open the picker, pre-checked with
                                             # everything registered — check/uncheck
                                             # to add or remove
claudeaibridge list-projects                # print all registered paths

La identidad de un proyecto es la ruta resuelta del archivo en el sistema, no hay ningún nombre separado que recordar.

claudeaibridge serve

Instala/inicia el servidor MCP como servicio en segundo plano con los parámetros (init termina llamando a esta misma vía al final del asistente) y regresa, sin bloquear tu terminal. Si el servicio de fondo ya está ejecutándose, serve solo reporta su URL de vez de instalarlo de nuevo.

Ejemplos:

claudeaibridge serve --ngrok                                    # install+start as a service
claudeaibridge serve --base-url https://your-domain.example     # bring your own tunnel
claudeaibridge serve --no-auth --foreground                     # local-only testing, blocking
claudeaibridge serve --transport stdio                          # local MCP client

claudeaibridge ngrok

claudeaibridge ngrok set-authtoken <token>   # one-time setup
claudeaibridge ngrok status                  # check whether a token is configured

Cada cuenta de ngrok (incluido el plan gratuito) tiene un dominio personalizado asignado de forma permanente, y el conector se vincula a ese dominio automáticamente con solo el authtoken, sin nada más que configurar. Si tienes plan de pago y prefieres un dominio propio, ejecuta su propio proceso ngrok http --domain=... y apunta claudeaibridge serve hacia él con --base-url (no con --ngrok).

Configuración

Todo se encuentra en ~/.config/claudeaibridge/ (o $XDG_CONFIG_HOME/claudeaibridge):

• projects.json — la lista de proyectos permitidos

• ngrok_authtoken — tu token de ngrok (chmod 600)

• oauth_state.json — clientes y tokens OAuth registrados, de modo que aprobar un Video de conector en claude.es es una única vez, no necesitas repetirlo en cada reinicio

• connector_url — la última URL de conector que haya impreso el servidor, para que claudeaibridge status tenga algo que mostrar aunque el servidor se ejecute como servicio de fondo (y no estés leyendo en time real su salida estándar)

Compilación desde el código fuente

pip install -e '.[build]'
./packaging/build.sh

La salida está en dist/claudeaibridge-<os>-<arch>. PyInstaller no permite compilación cruzada; esto solo compila para tu plataforma actual.

Ejecutar las pruebas

pip install -e '.[test]'
python tests/smoke_test.py        # core MCP tools, in-memory
python tests/oauth_flow_test.py   # full OAuth flow against a real subprocess
python tests/tunnel_test.py       # live ngrok test — needs NGROK_AUTHTOKEN set

Limitaciones conocidas

• Windows no es compatible, y el paso del servicio de fondo de init necesita systemd (Linux) o launchd (macOS); si no hay ninguno disponible, usar el primer plano.

• La vía de launchd (macOS) para el servicio en segundo plano está implementada, pero no verificada (se construyó y probó solo en Linux con systemd, por ser el único lugar disponible).

• Hay un solo widget por ahora: file_write/file_edit que muestran su cambio como diff de color. Se ha confirmado que funciona en vivo conectado a claude.ai.

Licencia

GPL-3.0-or-later.