KoboSend

KoboSend te ayuda a montar una experiencia parecida a "Send to Kindle", pero para lectores Kobo.

La idea es sencilla:

Envías un EPUB al ordenador
  -> KoboSend lo añade a Komga
  -> el Kobo sincroniza
  -> el libro aparece en My Books

El proyecto usa Komga como servidor compatible con Kobo Sync. El Kobo no recibe libros por push: descarga los libros cuando ejecutas Sync.

Estado

Este prototipo ya está validado con un Kobo Libra Colour:

• Envío local de EPUBs a Komga.
• Sincronización del Kobo desde la misma Wi-Fi.
• Sincronización desde otra red usando HTTPS con Tailscale Funnel.
• CLI kobosend para arrancar Komga, escanear la biblioteca, esperar la descarga del Kobo y apagar Komga.

Qué Necesitas

• Un ordenador que pueda ejecutar Docker. En macOS, Docker Desktop.
• Un Kobo compatible con Kobo Sync.
• Un EPUB sin DRM para probar.
• Un cable USB para editar una vez la configuración del Kobo.
• Opcional: Tailscale o Cloudflare Tunnel si quieres sincronizar desde fuera de casa.

Esta guía está escrita pensando sobre todo en macOS. En Linux o NAS el flujo es parecido, pero cambian algunas rutas y permisos.

No subas a GitHub tus EPUBs, .env, bases de datos de Komga ni API keys.

Instalación

Descarga o clona el proyecto. Después abre Terminal y entra en la carpeta:

cd /ruta/a/KoboSend

Crea tu configuración local:

cp .env.example .env

En macOS, comprueba tu usuario/grupo:

id -u
id -g

Abre .env y ajusta PUID y PGID si hace falta. En macOS normalmente son:

PUID=501
PGID=20

Arrancar Komga

Arranca el servidor:

docker compose up -d

Abre Komga:

http://localhost:25600

La primera vez Komga te pedirá crear un usuario.

Después crea una biblioteca nueva. Cuando Komga te pida la ruta de la biblioteca, escribe exactamente:

/data/books

Esa ruta es la carpeta vista desde Docker. En tu ordenador, los EPUBs viven aquí:

/ruta/a/KoboSend/data/books

Copia un EPUB de prueba en esa carpeta y lanza un scan desde Komga si no aparece automáticamente.

Preparar Kobo Sync

En Komga, el usuario que usará el Kobo necesita estos permisos:

KOBO_SYNC
FILE_DOWNLOAD

Genera una API key para el Kobo. Guárdala: será parte de la URL que pondremos en el lector.

Prueba En La Misma Wi-Fi

Busca la IP local del ordenador:

ipconfig getifaddr en0

Si no sale nada, mira la interfaz activa con:

route -n get default
ifconfig <interfaz>

El endpoint local tendrá este formato:

http://<IP-del-ordenador>:25600/kobo/<API_KEY_DEL_KOBO>

Ejemplo:

http://192.168.1.50:25600/kobo/xxxxxxxx

Editar El Kobo

Conecta el Kobo por USB y acepta conectar en el lector.

Haz una copia de seguridad del archivo de configuración:

cp "/Volumes/KOBOeReader/.kobo/Kobo/Kobo eReader.conf" "/Volumes/KOBOeReader/.kobo/Kobo/Kobo eReader.conf.backup"

Abre el archivo:

nano "/Volumes/KOBOeReader/.kobo/Kobo/Kobo eReader.conf"

Busca:

[OneStoreServices]

Cambia o añade:

api_endpoint=http://<IP-del-ordenador>:25600/kobo/<API_KEY_DEL_KOBO>

En nano:

• Buscar: Ctrl+W
• Guardar: Ctrl+O, luego Enter
• Salir: Ctrl+X

Expulsa el Kobo correctamente desde Finder y ejecuta Sync en el lector. Si todo va bien, el libro aparecerá en My Books.

Para volver al endpoint oficial de Kobo:

api_endpoint=https://storeapi.kobo.com

Sincronizar Desde Fuera De Casa

La IP local solo funciona si el Kobo está en la misma Wi-Fi que el ordenador.

Para sincronizar desde cualquier red necesitas una URL HTTPS pública:

api_endpoint=https://<tu-host-publico>/kobo/<API_KEY_DEL_KOBO>

Opciones:

• Tailscale Funnel: buena para probar rápido.
• Cloudflare Tunnel: recomendada para una instalación más estable.
• Caddy/Nginx + DDNS: opción clásica si puedes abrir puertos en el router.

Más detalle en docs/networking.md.

Configurar El CLI

El CLI necesita una API key diferente a la del Kobo. Esta API key es para que kobosend pueda pedirle a Komga que escanee la biblioteca.

Crea una API key de Komga para el CLI con un usuario que tenga rol ADMIN.

Luego guárdala en .env:

KOBOSEND_KOMGA_API_KEY=<API_KEY_ADMIN_DE_KOMGA>

Comprueba que todo está listo:

./bin/kobosend doctor

Ver estado:

./bin/kobosend status

Usar KoboSend

Enviar un EPUB:

./bin/kobosend send /ruta/a/libro.epub

Qué hace:

valida el EPUB
  -> abre Docker Desktop si está cerrado en macOS
  -> arranca Komga si estaba apagado
  -> copia el EPUB a data/books
  -> pide a Komga que escanee
  -> espera a que el Kobo descargue el libro
  -> apaga Komga si KoboSend lo arrancó

Arrancar Komga para redescargar libros o sincronizar el Kobo:

./bin/kobosend start

Parar Komga:

./bin/kobosend stop

Listar bibliotecas de Komga:

./bin/kobosend libraries

Usar kobosend Desde Cualquier Carpeta

En macOS con Homebrew:

ln -s /ruta/a/KoboSend/bin/kobosend /opt/homebrew/bin/kobosend

Después puedes ejecutar:

kobosend status
kobosend send /ruta/a/libro.epub
kobosend start
kobosend stop

Integracion Con OpenClaw Y Telegram

Este repo incluye una extension local para OpenClaw:

integrations/openclaw-kobosend

Permite este flujo desde Telegram:

/kobosend

Despues envias un EPUB como archivo/documento y OpenClaw ejecuta kobosend send en este ordenador.

Instalacion recomendada:

openclaw plugins install --link --dangerously-force-unsafe-install ./integrations/openclaw-kobosend
openclaw gateway restart

Consulta la guia de la extension para instalarla o modificarla.

Problemas Frecuentes

El Kobo No Descarga El Libro

Comprueba:

• Komga está encendido: kobosend status.
• El Kobo tiene Wi-Fi.
• El api_endpoint del Kobo apunta a la URL correcta.
• La API key del Kobo no contiene espacios ni caracteres extra.
• El libro aparece en Komga.

Mira logs:

docker compose logs -f --tail=120 komga

Docker No Arranca

Abre Docker Desktop manualmente y espera a que indique que está listo.

Luego:

kobosend status

kobosend doctor Dice Que Falta API Key

Edita .env y añade:

KOBOSEND_KOMGA_API_KEY=<API_KEY_ADMIN_DE_KOMGA>

No uses la API key del Kobo para esto. Usa una API key admin separada para el CLI.

Hay Varias Bibliotecas En Komga

Lista bibliotecas:

kobosend libraries

Pon el ID correcto en .env:

KOBOSEND_LIBRARY_ID=<LIBRARY_ID>

Seguridad

• Trata las API keys como contraseñas.
• Usa una API key distinta para cada Kobo.
• Usa otra API key distinta para el CLI.
• No publiques .env.
• No publiques la URL completa /kobo/<API_KEY>.
• No publiques la base de datos de Komga.
• No publiques EPUBs con copyright.

Documentación Avanzada

• Guía completa de instalación
• Red, HTTPS y acceso remoto
• CLI KoboSend
• Extension OpenClaw para Telegram
• Notas del prototipo validado

Referencias

• Komga Docker: https://komga.org/docs/installation/docker/
• Komga Kobo Sync: https://komga.org/docs/guides/kobo/
• Komga API: https://komga.org/docs/openapi/komga-api/
• Tailscale Funnel: https://tailscale.com/kb/1223/funnel
• Cloudflare Tunnel: https://developers.cloudflare.com/tunnel/

Apoyar El Proyecto

Si KoboSend te resulta útil y te apetece apoyar el tiempo invertido en el proyecto, puedes hacerlo escaneando cualquiera de estos QR:

PayPal

Revolut

Gracias por ayudar a que KoboSend siga mejorando.