Claude te preguntará qué quieres hacer con Holded, añadirá su servidor MCP oficial, esperará a que autorices el acceso en la web de Holded y te enseñará tus facturas pendientes de cobro y tus últimos contactos. Solo tienes que seguirle.
Quiero conectar mi cuenta de Holded a Claude Code para consultar mi facturación, contabilidad, contactos o proyectos y, cuando yo lo apruebe, preparar borradores. No soy técnico: guíame paso a paso, un paso cada vez, y espera a que te confirme antes de seguir.
CONTEXTO PARA TI
- Holded tiene un servidor MCP oficial: https://www.holded.com/es/desarrolladores/mcp (ayuda en español: https://help.holded.com/es/articles/15646468-connect-holded-with-ia). Es remoto, en https://mcp.holded.com/mcp, con OAuth 2.1 por Streamable HTTP: yo autorizo en app.holded.com y ninguna clave pasa por el chat. Según Holded, hace falta una cuenta de Holded con el acceso a la API activado. Las fuentes de Holded no coinciden sobre los planes: si tengo el plan Free, puede que no tenga acceso, así que compruébalo.
- En Claude Code se añade con: claude mcp add --transport http holded https://mcp.holded.com/mcp. Añádelo para mi usuario (--scope user) para que funcione desde cualquier carpeta. La primera vez hay que autorizarlo: en Claude Code, con /mcp se elige holded y se autentica, y se abre el navegador.
- También se puede añadir en claude.ai: Personalizar → Conectores → «+» → «Añadir conector personalizado» → pegar la URL → Conectar → iniciar sesión en Holded. En planes Team o Enterprise de Claude, un Owner de la organización tiene que añadirlo antes. Aún no está en el directorio de conectores de Claude: Holded lo anuncia como «muy pronto».
- Al autorizar se elige un perfil de permisos: «Analista» (solo lectura; la ayuda lo escribe «Analítico»), «Operativo» (lectura y escritura) o «Personalizado». Además, el asistente hereda los permisos de mi usuario de Holded. El acceso se revisa o se revoca en Holded, en Configuración → Desarrolladores → Credenciales.
- Tiene cientos de herramientas de lectura y escritura; la lista oficial está en https://www.holded.com/es/desarrolladores/mcp/herramientas (el número cambia).
- Alternativa, solo si el MCP no me sirve: la API REST v2 de Holded (doc: https://www.holded.com/es/desarrolladores). Base https://api.holded.com (por ejemplo, GET /api/v2/invoices), con la cabecera Authorization: Bearer y una API key. Las claves tienen permisos por ámbito (si falta uno, la API responde 403). Cubre ventas (facturas, rectificativas, proformas, presupuestos, pedidos, albaranes, recurrentes, tickets), compras, contactos, productos y stock, contabilidad (plan contable, asientos), tesorería, impuestos, pagos, webhooks, proyectos y equipo. La clave se crea en Configuración → Desarrolladores → Credenciales → «Agregar API Token» → «Crear Token».
- Límites (https://www.holded.com/es/desarrolladores/limite-de-tasa): por cuenta, por minuto y con una cuota mensual según el plan (Starter, 60 por minuto y 500 llamadas al mes; Premium, 600 por minuto y 100.000). Si me paso, responde 429 con Retry-After. En un plan pequeño, nada de barridos enteros: pide solo lo que haga falta.
QUÉ QUIERO QUE HAGAS
1. ENTENDER: pregúntame, de una en una y con opciones para elegir: qué quiero (consultar facturas y cobros, contabilidad, contactos o proyectos, o también preparar borradores de facturas o presupuestos); si es algo puntual o recurrente; y qué plan de Holded tengo y si mi usuario es el administrador de la cuenta.
2. REVISAR: comprueba tú mismo si Claude Code ya tiene el servidor de Holded (claude mcp list o sus herramientas). Si ya está y responde, salta al paso 5.
3. RECOMENDAR: dime en dos frases qué vía encaja. Por defecto, el MCP oficial con el perfil «Analista». Propón la API solo si el MCP no me sirve, y nunca un servidor MCP de la comunidad.
4. CONECTAR: con el MCP, ejecuta tú el comando de arriba (con --scope user), pidiéndome permiso antes. Luego dime que escriba /mcp, elija holded y le dé a autenticar; se abrirá app.holded.com. Antes de que apruebe, explícame en una frase qué estoy dando, que elija «Analista» y que puedo rechazarlo. Cuando te diga «OK», comprueba que ves sus herramientas; si no, dime cómo reiniciar Claude Code. Si eligimos la API: guíame para crear la clave en Holded con solo los ámbitos que necesite; cuando la haya copiado y te diga «OK», léela tú del portapapeles (pbpaste en Mac; Get-Clipboard de PowerShell en Windows) y guárdala directamente como variable de entorno de usuario HOLDED_API_KEY (en Mac, una línea export en ~/.zshrc; en Windows, [Environment]::SetEnvironmentVariable con ámbito User), sin mostrarla, repetirla ni escribirla en el chat. Comprueba solo que no está vacía y después vacía el portapapeles.
5. PROBAR (solo lectura): dime a qué cuenta de Holded estás conectado y enséñame en tablas cortas las facturas pendientes de cobro (cliente, fecha, importe), los últimos 5 contactos y las ventas de este mes.
6. RECORDAR: crea una skill personal con cómo te conectas a Holded (MCP o API), el perfil que elegí, lo que suelo pedirte, los límites de mi plan y las reglas de abajo. Así la próxima vez me basta con preguntarte.
Reglas: trabaja con el perfil «Analista» (solo lectura) salvo que yo pida otra cosa. No crees, edites, envíes ni borres facturas, presupuestos, contactos ni asientos salvo que yo lo pida de forma explícita, y antes enséñame el borrador completo y espera mi OK. Una factura emitida tiene efectos fiscales: no se borra a la ligera, así que si hay que corregir una, pregúntame antes. Antes de sobrescribir cualquier dato, guarda el original en un fichero de esta carpeta para poder volver atrás. Respeta los límites de mi plan: nada de recorrer toda la cuenta de golpe. Nunca me pidas una clave en el chat. Si algo falla, explícamelo en lenguaje sencillo antes de intentar arreglarlo.
CÓMO TRABAJAR CONMIGO
- Explícame cada paso como a un niño de 10 años: frases cortas, sin jerga y, si usas una palabra técnica, dime en una línea qué es. Si te digo que soy técnico, ve al grano.
- Cuando tengas que preguntarme algo, hazlo de una pregunta en una y con opciones para elegir (usa la herramienta de preguntas con opciones si la tienes), con una línea que explique cada opción.
- Si hay que instalar algo, dime en una línea qué es y para qué sirve, y ofrécete a instalarlo tú con mi permiso. Si algo falla, cuéntame en palabras sencillas qué ha pasado y cuál es el siguiente intento, antes de probarlo.
- Lo que te cuento arriba puede haberse quedado viejo. Antes de empezar, comprueba en la documentación oficial que sigue vigente; si algo no coincide, manda la documentación y dime qué ha cambiado.
- Si tienes navegador (el navegador integrado de la app de Claude o Claude in Chrome), hazlo tú todo lo que puedas en vez de mandarme a una web: ábrela tú, navega hasta la pantalla exacta, rellena lo que no sea secreto y léeme lo que haga falta. Si arriba pone que yo vaya a una página o pulse algo, tómalo como lo que hay que conseguir y hazlo tú con el navegador. Pídeme a mí, de un paso en uno, solo lo que no puedes hacer: iniciar sesión, aprobar permisos, pagar o copiar una clave; tú no escribes contraseñas ni claves en ninguna web. Si no tienes navegador, entonces guíame con instrucciones.
- Si hacen falta claves o algo más para conectarte (scripts, configuración), guárdalo en un sitio fijo de mi usuario, fuera de esta carpeta y de cualquier repositorio, que solo yo pueda leer. Nunca en el chat ni dentro de una skill.
- La skill de RECORDAR, hazla personal (que funcione desde cualquier carpeta) y apunta en ella: cómo conectarte, con qué cuenta o usuario, dónde están las claves (el sitio, nunca el valor), qué suelo pedirte, las reglas de arriba y la fecha en que comprobaste la documentación. Si algo deja de funcionar porque el servicio cambió, mira la documentación, arréglalo y actualiza la skill.
- Mis preferencias y lo que haya fallado van en un LEARNINGS.md aparte, en la misma carpeta de esa skill (una línea por aprendizaje, con fecha y el porqué). El primer paso de la skill es leerlo y aplicarlo. Para que nunca se te olvide proponer aprendizajes nuevos al terminar, añade al frontmatter de su SKILL.md este hook, cambiando <nombre-de-la-skill> por su nombre (inyecta un recordatorio una vez por uso; no lo cambies por un bloqueo, que entra en bucle):
hooks:
Stop:
- hooks:
- type: command
once: true
command: |
grep -q '"stop_hook_active":true' && exit 0
echo '{"hookSpecificOutput":{"hookEventName":"Stop","additionalContext":"Antes de terminar: si en este uso de la skill <nombre-de-la-skill> el usuario corrigió algo, algo falló o mostró una preferencia, propón de 0 a 3 aprendizajes para su LEARNINGS.md (fecha, una línea y el porqué), enséñalos y pide OK antes de escribirlos. Si ya propusiste aprendizajes en este turno, no los repitas. Si no hay nada que aprender, termina sin añadir nada."}}'