Configuración de Claude Code — instalación, permisos, hooks y MCP en la primera hora

Claude Code es el CLI agéntico oficial de Anthropic. Es potente una vez configurado, pero saltarse el modelo de permisos, CLAUDE.md, los hooks y MCP en el momento de la instalación significa que repetirás el mismo trabajo manual a diario. Esta guía recorre macOS / Linux / Windows (Git Bash o WSL2) instalación → autenticación → guía del proyecto → permisos → hooks → MCP, en orden.

Está dirigida a desarrolladores que ya usan git/Node con comodidad pero son nuevos en Claude Code o lo usan sin una configuración ordenada.

TL;DR

1. Node.js 20+ → npm install -g @anthropic-ai/claude-code → claude → autenticación en el navegador
2. Colocar CLAUDE.md (1–2 pantallas) + .claude/settings.json (permisos/env/hooks) en la raíz del proyecto
3. Tres slash commands para empezar: /help, /config, /init
4. Cuando un comando siga siendo denegado, añadir un patrón a permissions.allow
5. Añadir servidores MCP solo cuando los necesites: preferir stdio local y mantener los tokens en variables de entorno

Requisitos previos

• Node.js 20+ — node -v. ¿Versión antigua? Actualizar vía mise o nvm
• Cuenta de Anthropic — console.anthropic.com o suscripción a Claude.ai Pro/Max
• Git — utilizado por el CLI para inspeccionar el proyecto. En macOS ver /mac/initial-setup
• SO: macOS / Linux / Windows (Git Bash o WSL2 recomendados; PowerShell puro funciona pero reduce la compatibilidad de hooks basados en sh)

1. Instalar (5 minutos)

1.1 Instalación global con npm

npm install -g @anthropic-ai/claude-code

¿Error de permisos? En lugar de sudo, mueve el prefijo de npm a tu home:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=$HOME/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @anthropic-ai/claude-code

1.2 Primera ejecución y autenticación

Accede al directorio del proyecto y ejecuta:

cd ~/projects/my-repo
claude

En la primera ejecución se abre una pestaña del navegador para la autenticación de Anthropic. Tras iniciar sesión, el CLI inicia un chat. El token se almacena en el keychain del SO para que no tengas que volver a autenticarte cada vez.

1.3 Verificar

claude --version
# muestra algo como 0.x.x

2. Tres slash commands esenciales para empezar

Dentro del CLI, los comandos que empiezan con / son slash commands. Tres son suficientes para empezar:

Ejecutar /init una vez por cada nuevo proyecto — inspecciona la estructura de carpetas, el lenguaje y las herramientas de build para producir un borrador inicial plausible que luego puedes refinar.

3. CLAUDE.md — guía del proyecto (el elemento más importante)

CLAUDE.md es un archivo markdown en la raíz del proyecto que se carga automáticamente al inicio de cada sesión. Las reglas escritas aquí se convierten en prioridad máxima para toda la sesión.

Ejemplo de CLAUDE.md bien estructurado

# Proyecto — guía para Claude
 
## Persona
(opcional) Sugerencia de rol, por ejemplo, "Actúa como un ingeniero senior que revisa los diffs críticamente."
 
## Stack
- Framework: Next.js 16 (App Router)
- Lenguaje: TypeScript strict
- BD: Supabase
 
## Comandos
- Servidor de desarrollo: `pnpm dev`
- Build: `pnpm build`
- Tests: `pnpm test`
 
## Convenciones
- No usar `any` (TS strict)
- Nombres de archivos: kebab-case (rutas), camelCase (utils)
- Nunca hardcodear secretos
 
## Git
- Commits: `[Proyecto] {tipo}: {desc}` — feat/fix/refactor/...
- Push directo a main: OK (en solitario) / PR requerido (en equipo)
 
## Principios de trabajo
1. Planificar primero cuando los cambios tocan 5+ archivos / nuevo módulo / arquitectura
2. Tras cambios de código, no declarar "completado" hasta que lint+build+tests pasen
3. Secretos · migraciones de BD · pushes externos requieren aprobación explícita

Consejos

• Mantenerlo corto: 1–2 pantallas. Lo que sea más largo va a memory/rules/{tema}.md y se enlaza desde CLAUDE.md.
• Usar un archivo por proyecto; colocar la guía compartida entre proyectos en ~/.claude/CLAUDE.md.
• Hacer commit de CLAUDE.md a git para que los compañeros y otras máquinas lo recojan.

4. .claude/settings.json — permisos, variables de entorno y hooks

El archivo que controla el comportamiento en tiempo de ejecución. El bloque que más editarás es permissions.

4.1 Esqueleto

{
  "permissions": {
    "allow": [
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(pnpm test:*)",
      "Read(/Users/me/projects/**)"
    ],
    "deny": [
      "Bash(rm -rf /:*)",
      "Bash(sudo *)"
    ]
  },
  "env": {
    "EDITOR": "code --wait"
  },
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          { "type": "command", "command": "echo '[Inicio de sesión] $(date)'" }
        ]
      }
    ]
  }
}

4.2 Reglas de permisos (permissions.allow / deny)

• Cuando un Bash(...) sigue siendo denegado, añadirlo a allow como patrón
• Los patrones usan coincidencia de prefijo: Bash(pnpm:*) permite todo lo que empiece con pnpm
• Fijar los patrones peligrosos (rm -rf, sudo, curl … | bash) en deny por seguridad

💡 Para añadir masivamente comandos de solo lectura comunes, ejecutar el skill integrado /fewer-permission-prompts dentro del CLI — escanea tus transcripts y sugiere una lista de permitidos.

4.3 Plantilla descargable

La misma configuración como archivo listo (verificar antes de usar):

# 1. Descargar
curl -fsSL https://devalice.jaceclub.com/assets/ai-agents/claude-code/settings.example.json -o .claude/settings.example.json
 
# 2. Verificar SHA-256
shasum -a 256 .claude/settings.example.json
# esperado: 22898a20ade2b3497f8299a8ca6139112c476e0a0a4075e1a05123a02c8266ac
 
# 3. Inspeccionar, luego copiar al lugar correcto
less .claude/settings.example.json
cp .claude/settings.example.json .claude/settings.json

No pegar secretos (claves API, etc.) en settings.json. Leerlos desde el env del SO o un .env ignorado por git.

4.4 Global, proyecto y local

5. Hooks: disparadores automáticos

Los hooks ejecutan comandos de shell en eventos específicos. Los principales:

Ejemplo 1: mostrar información del entorno al inicio de sesión

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "printf '[Inicio de sesión] %s\\nRama: %s\\n' \"$(date '+%F %T')\" \"$(git branch --show-current 2>/dev/null || echo none)\""
          }
        ]
      }
    ]
  }
}

Ejemplo 2: bloquear escrituras en archivos de credenciales

PreToolUse puede bloquear mediante código de salida (1 = advertir, 2 = bloquear).

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | grep -qE '\\.env$|secrets/|private_key' && { echo 'BLOQUEADO: archivo secreto'; exit 2; } || exit 0"
          }
        ]
      }
    ]
  }
}

Detalles de la especificación: /help → enlace a docs, o la documentación oficial. Al depurar, empieza con un hook echo de una línea para confirmar que se dispara.

6. Servidores MCP: solo cuando los necesites

MCP (Model Context Protocol) es el estándar para exponer herramientas externas a Claude Code. Existen integraciones para GitHub, Slack, Linear, Figma, y puedes escribir las tuyas.

Registro

Añadir a mcpServers en .claude/settings.json:

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

${GITHUB_TOKEN} se expande desde tu env de shell — pon export GITHUB_TOKEN=... en .zshrc o .envrc (direnv) para mantener el secreto fuera de settings.json.

Seguridad

• Preferir servidores stdio locales (command: "npx" o un binario local): superficie de ataque menor que los servidores RPC en red
• Solo paquetes verificados: @modelcontextprotocol/*, @upstash/*, etc. Inspeccionar los paquetes desconocidos antes de usarlos
• Secretos vía variables de entorno: settings.json a menudo se hace commit en git; nunca poner tokens en línea

7. Integración con IDE: VS Code y Cursor

Claude Code es un CLI, pero encaja bien dentro de los IDEs:

• Terminal integrada de VS Code / Cursor: ejecuta claude directamente. Edita archivos en el IDE y chatea en el terminal. La opción más sencilla.
• Extensión de VS Code: busca "Claude Code" en el marketplace para abrirlo en un panel lateral.
• JetBrains (IntelliJ/PyCharm/…): plugin disponible en el marketplace de JetBrains.

Si ya usas un editor con IA nativa (Cursor, Windsurf), mantén Claude Code para las tareas de "muchos archivos / shell / git" y deja que la IA del editor gestione las ediciones en línea.

8. Verificar: ¿está completa la configuración?

# 1. Instalación
claude --version
 
# 2. Archivos de configuración del proyecto
ls -la CLAUDE.md .claude/settings.json
 
# 3. Configuración global (opcional)
ls -la ~/.claude/settings.json 2>/dev/null && echo "global OK" || echo "sin global"
 
# 4. Autenticación — ejecutar `claude` y buscar el banner de bienvenida
#    > claude
#    │ Welcome to Claude Code!

Si los cuatro pasan, la configuración está completa. Primera tarea real: ejecutar claude en el directorio del proyecto y preguntar algo como "Describe la estructura de este repositorio en un párrafo."

9. Solución de problemas

command not found: claude

• El directorio bin global de npm no está en PATH. Ejecuta npm config get prefix para encontrarlo y añade <prefijo>/bin a ~/.zshrc / ~/.bashrc.
• Windows Git Bash: npm config get prefix debería devolver C:\Users\<tú>\AppData\Roaming\npm; esa ruta debe estar en PATH.

La autenticación en el navegador no se abre en la primera ejecución

• Entorno sin cabeza (SSH, WSL2): copia la URL que muestra el CLI en un navegador manualmente.
• Si la autenticación sigue fallando, elimina el caché de tokens en ~/.claude/ e inténtalo de nuevo.

El prompt de permiso aparece en cada comando Bash

• Añade los comandos de solo lectura más habituales a permissions.allow en .claude/settings.json.
• O usa /config → modo de permiso acceptEdits (aprueba automáticamente las ediciones; sigue preguntando para el shell).

Los hooks no se disparan

# 1. ¿JSON válido?
cat .claude/settings.json | jq .
 
# 2. Simplificar el comando y verificar
# command: "echo HOOK_FIRED >> /tmp/claude-hook.log"

Un JSON roto deshabilita silenciosamente la sección de hooks.

El servidor MCP no aparece

• Usa /mcp dentro del CLI para ver los servidores registrados y su estado.
• Confirma que command está en PATH (which npx).
• Revisa los logs en ~/.claude/logs/ o stderr.

10. Qué sigue

Al llegar aquí, Claude Code ya es utilizable a diario. Los próximos pasos:

• Patrones de flujo de trabajo: multi-agente, modo de planificación, subagentes (próximamente)
• Comparación con Cursor: /ai-agents/cursor-setup
• Hooks avanzados: SessionStart para sincronización de memoria, PreToolUse para puertas de seguridad
• Escribir tu propio servidor MCP: exponer herramientas internas (próximamente)

Referencias

• Documentación oficial de Claude Code
• MCP oficial
• Anthropic Console — claves API / uso
• Incidencias de GitHub de Claude Code — informes de bugs

Registro de cambios

• 2026-05-12 — Traducción inicial al español (devAlice M2 i18n seed)