¿Por qué conectar GitHub con Claude Code?

Claude Code puede ayudarte a recorrer repositorios, entender bases de código e incluso crear o actualizar archivos — pero solo si le das los permisos y la configuración adecuados. MCP (Model Context Protocol) hace de puente y permite a Claude interactuar con los repositorios de GitHub a través de una interfaz estandarizada.

Una vez configurado, puedes:

  • Recorrer los archivos del repositorio y entender la estructura del código
  • Crear y gestionar incidencias y solicitudes de incorporación de cambios
  • Revisar cambios sin salir de tu editor
  • Ejecutar todo esto en modo de solo lectura por seguridad, si lo prefieres

El reto está en configurarlo bien. Un solo error — un archivo JSON mal formado, permisos de token equivocados o una variable de entorno incorrecta — te deja mirando errores de autenticación sin un diagnóstico claro.

Servidores MCP locales frente a remotos

Antes de empezar tienes que decidir cómo vas a ejecutar el servidor MCP de GitHub. Esa elección afecta a tu configuración, a la seguridad y a cómo accede Claude a GitHub.

Servidores MCP locales

Un servidor local se ejecuta en tu máquina como un proceso de Node.js. Usa el transporte stdio, es decir, Claude se comunica con él directamente por entrada y salida estándar. Los servidores locales tienen acceso directo a tu sistema de archivos y a tus variables de entorno.

Cuándo usar el local: Quieres control total del servidor, prefieres no enviar peticiones por la red o necesitas una integración estrecha con tu entorno de desarrollo.

Configuración: Se guarda en un archivo JSON, normalmente en ~/.claude.json o en un .mcp.json dentro del directorio de tu proyecto.

Servidores MCP remotos

Un servidor remoto está alojado en otro sitio — por un proveedor o en tu propia infraestructura. Claude se comunica con él por HTTP, enviando peticiones y recibiendo respuestas por la red.

Cuándo usar el remoto: Quieres el alojamiento oficial de GitHub, no quieres gestionar procesos de servidor o necesitas compartir la misma configuración en todo un equipo.

Configuración: Más simple; solo indicas la URL del servidor y las credenciales desde la interfaz de Claude o el archivo de configuración.

¿Primera vez? Empieza por el remoto si GitHub lo ofrece. Hay menos que depurar. Ya migrarás al local más adelante si necesitas más control.

Paso 1: Crea un token de acceso personal de GitHub (PAT)

Claude necesita permiso para acceder a tu cuenta de GitHub. Ese permiso llega mediante un token de acceso personal.

Tokens de grano fino frente a tokens clásicos

GitHub ofrece dos tipos de token. Los de grano fino son más nuevos y más seguros porque te dan control granular sobre exactamente qué puede hacer Claude. Los clásicos son más amplios.

GitHub recomienda los tokens de grano fino. Con ellos puedes conceder acceso de «lectura» o de «lectura y escritura» a tipos de recurso concretos — repositorios, incidencias, solicitudes de cambios — de forma independiente. Esto sigue el principio de mínimo privilegio: Claude recibe solo los permisos que de verdad necesita.

Crear un token de grano fino

Ve a GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens. Haz clic en «Generate new token».

Rellena los datos:

  • Nombre del token: Algo descriptivo, como «Claude Code MCP»
  • Caducidad: 90 días es un valor por defecto sensato. Cuanto más corto, más seguro.
  • Propietario del recurso: Tu cuenta (o tu organización, si tienes los permisos adecuados)
  • Acceso a repositorios: «Only select repositories» (elige cuáles necesita Claude), o «All repositories» si quieres que Claude acceda a cualquier repositorio tuyo

Permisos mínimos para el MCP de GitHub

Los permisos dependen de lo que quieras que haga Claude. El principio es este: concede solo lo que necesitas.

  • Leer el contenido del repositorio: Contents → Read-only
  • Leer incidencias y solicitudes de cambios: Issues → Read-only; Pull requests → Read-only
  • Crear incidencias: Issues → Read and write
  • Aprobar solicitudes de cambios: Pull requests → Read and write
  • Leer información de la organización: Members → Read-only (si trabajas con repositorios de organización)

Empieza con lo mínimo. Si Claude te dice que le falta permiso, añade el siguiente y vuelve a generar el token.

Copia y guarda el token con cuidado

Tras crearlo, GitHub te muestra el token una sola vez. Cópialo de inmediato. Si lo pierdes, tendrás que borrarlo y crear uno nuevo.

No escribas tokens a mano en repositorios públicos, en el control de versiones ni en ventanas de chat. Trátalos como contraseñas.

Paso 2: Instala y configura el servidor MCP de GitHub

Opción A: instalación local (npm)

Instala el servidor MCP oficial de GitHub con npm:

npm install -g @modelcontextprotocol/server-github

Después configúralo. En macOS o Linux, edita (o crea) ~/.claude.json:

{ "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_YOUR_TOKEN_HERE" } } } }

En Windows, la configuración cambia un poco. CMD necesita una envoltura extra:

{ "mcpServers": { "github": { "command": "cmd", "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_YOUR_TOKEN_HERE" } } } }

Sustituye ghp_YOUR_TOKEN_HERE por tu token real.

JSON is strict. One missing comma or mismatched bracket silently breaks all servers. Validate your JSON before restarting Claude: use cat ~/.claude.json | python3 -m json.tool or an online JSON validator.

Opción B: instalación remota

Si prefieres no gestionar el proceso del servidor, usa la versión alojada por GitHub. En Claude Code, pulsa el botón «+», ve a Connectors → Manage Connectors y elige GitHub de la biblioteca o añade la URL de un servidor personalizado.

Pegarás tu token cuando te lo pida.

El modo de solo lectura impide que Claude modifique nada en GitHub — sin incidencias nuevas, sin commits, sin borrados. Es perfecto para revisar código, explorar y aprender.

Activar el modo de solo lectura

En servidores locales, añade la variable de entorno a tu configuración de .claude.json:

"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_YOUR_TOKEN_HERE", "GITHUB_READ_ONLY": "1" }

Como alternativa, pasa el indicador directamente al arrancar el servidor:

npx @modelcontextprotocol/server-github --read-only

En servidores remotos, si tienes el tuyo propio, añade la cabecera X-MCP-Readonly: true a tus peticiones. Si usas la versión alojada por GitHub, consulta su documentación para la configuración de solo lectura.

Con el modo de solo lectura activo, Claude solo tendrá acceso a herramientas de lectura. Si intenta crear una incidencia, recibirás un error de permisos. El modo actúa como filtro de seguridad duro y prevalece sobre cualquier otra configuración.

Errores habituales y cómo resolverlos

El servidor no aparece en Claude Code

Causa: Normalmente un archivo JSON de configuración roto. El JSON falla en silencio.

Solución: Valida tu archivo .claude.json. Usa cat ~/.claude.json | python3 -m json.tool o un validador en línea. Corrige los errores de sintaxis y reinicia Claude.

«Authentication failed: Bad credentials»

Causa: Tu token es incorrecto, ha caducado o no tiene permisos suficientes.

Fix:

  • Copia un token nuevo desde GitHub. Pégalo directamente en tu configuración (ojo con los espacios o saltos de línea de más).
  • Comprueba que tu token no haya caducado. GitHub muestra la caducidad en Settings → Personal access tokens.
  • Si está a punto de caducar, bórralo y crea uno nuevo.
  • Verifica que tu token tenga al menos el permiso repo (en tokens clásicos) o su equivalente de grano fino.

«Command not found» al arrancar Claude

Causa: Claude no encuentra el comando npx. Pasa porque la aplicación gráfica (Claude Desktop o Cursor) tiene un entorno distinto al de tu terminal.

Fix:

  • Asegúrate de que Node.js está instalado de forma global: which node debería devolver una ruta.
  • Usa rutas absolutas en tu configuración si puedes. En lugar de "npx", pon la ruta completa (por ejemplo "/usr/local/bin/npx", o "C:\\Program Files\\nodejs\\npm.cmd" en Windows).
  • Reinicia Claude después de hacer cambios.

«Server reconnection failed» tras autenticarse

Causa: Un problema temporal de conexión o la caducidad del token OAuth.

Solución: Reinicia Claude Code. Si pasa una y otra vez, borra el servidor y vuelve a añadirlo con un token nuevo.

Recomendaciones de seguridad

  • Usa tokens de grano fino. Son más nuevos y te dan control preciso sobre los permisos.
  • Pon una caducidad. 90 días es un buen equilibrio. Cuanto más corta, más seguro.
  • Rótalos con regularidad. Borra los tokens viejos y crea nuevos cada pocos meses.
  • Empieza en solo lectura. Actívalo por defecto. Añade permisos de escritura solo si Claude los necesita de verdad.
  • Limita el acceso a repositorios. Usa «Only select repositories» en lugar de dar a Claude acceso a todos tus repositorios.
  • Nunca dejes tokens escritos en el control de versiones. Usa variables de entorno o archivos de configuración aparte que no subas.
  • Audita tus tokens. Entra en GitHub Settings → Developer settings → Personal access tokens y revisa cuáles siguen activos. Borra lo que no uses.

Preguntas frecuentes

¿Puedo usar el mismo token en varias máquinas?

Sí. Un token está ligado a tu cuenta de GitHub, no a una máquina concreta. Puedes usar el mismo en tu portátil, tu equipo de sobremesa y tu servidor. Dicho esto, si una máquina se ve comprometida, quien ataque tiene acceso a todas las que usan ese token. En entornos de alta seguridad, plantéate un token distinto por máquina o por entorno (desarrollo, preproducción, producción).

¿Y si quiero que Claude modifique repositorios?

Crea un segundo token con permisos de escritura (por ejemplo Contents → Read and write y Pull requests → Read and write) y úsalo para las tareas que requieran modificaciones. Guarda el token de solo lectura para explorar y navegar. Así reduces el radio de daño si el token de escritura se filtra.

¿Es seguro usar MCP con código privado?

En general sí, con matices. Tu código se queda en tu repositorio; Claude lo lee y lo procesa en servidor (de Anthropic). Revisa la política de privacidad de Anthropic y las reglas de gobernanza de datos de tu empresa. Si tu código es muy sensible, plantéate ejecutar Claude en local o en un entorno aislado. En repositorios privados de GitHub, el token solo da acceso a los repositorios que hayas autorizado expresamente.

¿Uso el servidor MCP oficial de GitHub o me construyo el mío?

Usa el oficial de GitHub. Está mantenido, probado y se actualiza con funciones nuevas de forma regular. Construir el tuyo solo hace falta si necesitas lógica a medida o integración con sistemas internos que el servidor de GitHub no soporta.

¿Qué pasa si mi token caduca?

Claude recibirá errores de autenticación al intentar usar GitHub. Mira el mensaje de error — normalmente dice que el token no es válido o ha caducado. Genera un token nuevo, actualiza tu configuración y reinicia Claude.