Por que conectar o GitHub ao Claude Code?

O Claude Code pode ajudar você a percorrer repositórios, entender bases de código e até criar ou atualizar arquivos — mas só se você der as permissões e a configuração certas. O MCP (Model Context Protocol) faz a ponte e permite que o Claude interaja com repositórios do GitHub por uma interface padronizada.

Depois de configurado, você pode:

  • Percorrer os arquivos do repositório e entender a estrutura do código
  • Criar e gerenciar issues e pull requests
  • Revisar alterações sem sair do seu editor
  • Rodar tudo isso em modo somente leitura, por segurança, se preferir

O desafio está em configurar direito. Um único erro — um arquivo JSON malformado, escopos de token errados ou uma variável de ambiente incorreta — deixa você olhando para erros de autenticação sem diagnóstico claro.

Servidores MCP locais e remotos

Antes de começar, você precisa decidir como vai rodar o servidor MCP do GitHub. Essa escolha afeta a sua configuração, a segurança e o modo como o Claude acessa o GitHub.

Servidores MCP locais

Um servidor local roda na sua máquina como um processo Node.js. Ele usa o transporte stdio, ou seja, o Claude se comunica com ele direto pela entrada e saída padrão. Servidores locais têm acesso direto ao seu sistema de arquivos e às suas variáveis de ambiente.

Quando usar o local: Você quer controle total do servidor, prefere não mandar requisições pela rede ou precisa de integração estreita com o seu ambiente de desenvolvimento.

Configuração: Fica em um arquivo JSON, normalmente em ~/.claude.json ou em um .mcp.json dentro do diretório do projeto.

Servidores MCP remotos

Um servidor remoto fica hospedado em outro lugar — por um fornecedor ou na sua própria infraestrutura. O Claude se comunica com ele por HTTP, mandando requisições e recebendo respostas pela rede.

Quando usar o remoto: Você quer a hospedagem oficial do GitHub, não quer gerenciar processos de servidor ou precisa compartilhar a mesma configuração com um time inteiro.

Configuração: Mais simples; você só informa a URL do servidor e as credenciais pela interface do Claude ou pelo arquivo de configuração.

Primeira vez? Comece pelo remoto, se o GitHub oferecer. Há menos coisa para depurar. Você migra para o local depois, se precisar de mais controle.

Passo 1: Crie um token de acesso pessoal do GitHub (PAT)

O Claude precisa de permissão para acessar a sua conta do GitHub. Essa permissão vem por um token de acesso pessoal.

Tokens de granularidade fina e tokens clássicos

O GitHub oferece dois tipos de token. Os de granularidade fina são mais novos e mais seguros porque dão controle granular sobre exatamente o que o Claude pode fazer. Os clássicos são mais amplos.

O GitHub recomenda os tokens de granularidade fina. Com eles você concede acesso de “leitura” ou de “leitura e escrita” a tipos específicos de recurso — repositórios, issues, pull requests — de forma independente. Isso segue o princípio do menor privilégio: o Claude recebe só as permissões de que realmente precisa.

Criar um token de granularidade fina

Vá em GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens. Clique em “Generate new token”.

Preencha os dados:

  • Nome do token: Algo descritivo, como “Claude Code MCP”
  • Validade: 90 dias é um padrão sensato. Quanto mais curto, mais seguro.
  • Dono do recurso: A sua conta (ou a sua organização, se você tiver as permissões adequadas)
  • Acesso a repositórios: “Only select repositories” (escolha de quais o Claude precisa), ou “All repositories” se quiser que o Claude acesse qualquer repositório seu

Permissões mínimas para o MCP do GitHub

As permissões dependem do que você quer que o Claude faça. O princípio é este: conceda só o necessário.

  • Ler o conteúdo do repositório: Contents → Read-only
  • Ler issues e pull requests: Issues → Read-only; Pull requests → Read-only
  • Criar issues: Issues → Read and write
  • Aprovar pull requests: Pull requests → Read and write
  • Ler informações da organização: Members → Read-only (se você trabalha com repositórios de organização)

Comece pelo mínimo. Se o Claude disser que falta permissão, acrescente a próxima e gere o token de novo.

Copie e guarde o token com cuidado

Depois de criado, o GitHub mostra o token uma única vez. Copie na hora. Se perder, vai ter que apagá-lo e criar outro.

Não escreva tokens direto em repositórios públicos, no controle de versão ou em janelas de chat. Trate-os como senhas.

Passo 2: Instale e configure o servidor MCP do GitHub

Opção A: instalação local (npm)

Instale o servidor MCP oficial do GitHub pelo npm:

npm install -g @modelcontextprotocol/server-github

Depois configure. No macOS ou no Linux, edite (ou crie) o ~/.claude.json:

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

No Windows, a configuração muda um pouco. O CMD precisa de um invólucro extra:

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

Troque ghp_YOUR_TOKEN_HERE pelo seu 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.

Opção B: instalação remota

Se você prefere não gerenciar o processo do servidor, use a versão hospedada pelo GitHub. No Claude Code, clique no botão “+”, vá em Connectors → Manage Connectors e escolha o GitHub na biblioteca ou adicione a URL de um servidor personalizado.

Você vai colar o seu token quando for pedido.

O modo somente leitura impede que o Claude altere qualquer coisa no GitHub — sem issues novas, sem commits, sem exclusões. É perfeito para revisar código, explorar e aprender.

Ativar o modo somente leitura

Em servidores locais, acrescente a variável de ambiente à sua configuração no .claude.json:

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

Como alternativa, passe o parâmetro direto ao subir o servidor:

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

Em servidores remotos, se o servidor for seu, acrescente o cabeçalho X-MCP-Readonly: true às suas requisições. Se usar a versão hospedada pelo GitHub, confira a documentação deles para a configuração somente leitura.

Com o modo somente leitura ligado, o Claude só terá acesso às ferramentas de leitura. Se tentar criar uma issue, você recebe um erro de permissão. O modo funciona como um filtro de segurança rígido e prevalece sobre qualquer outra configuração.

Erros comuns e como resolver

O servidor não aparece no Claude Code

Causa: Normalmente um arquivo JSON de configuração quebrado. O JSON falha em silêncio.

Solução: Valide o seu arquivo .claude.json. Use cat ~/.claude.json | python3 -m json.tool ou um validador on-line. Corrija os erros de sintaxe e reinicie o Claude.

“Authentication failed: Bad credentials”

Causa: O seu PAT está incorreto, venceu ou não tem escopos suficientes.

Fix:

  • Copie um token novo do GitHub. Cole direto na sua configuração (cuidado com espaços ou quebras de linha extras).
  • Confira se o seu token não venceu. O GitHub mostra a validade em Settings → Personal access tokens.
  • Se estiver perto de vencer, apague e crie outro.
  • Confirme que o seu token tem pelo menos o escopo repo (em tokens clássicos) ou as permissões equivalentes de granularidade fina.

“Command not found” ao iniciar o Claude

Causa: O Claude não encontra o comando npx. Isso acontece porque o aplicativo gráfico (Claude Desktop ou Cursor) tem um ambiente diferente do seu terminal.

Fix:

  • Garanta que o Node.js está instalado globalmente: which node deve devolver um caminho.
  • Use caminhos absolutos na sua configuração, se possível. Em vez de "npx", use o caminho completo (por exemplo "/usr/local/bin/npx", ou "C:\\Program Files\\nodejs\\npm.cmd" no Windows).
  • Reinicie o Claude depois de fazer alterações.

“Server reconnection failed” depois da autenticação

Causa: Um problema temporário de conexão ou o vencimento do token OAuth.

Solução: Reinicie o Claude Code. Se isso se repetir, apague o servidor e adicione de novo com um token novo.

Recomendações de segurança

  • Use tokens de granularidade fina. São mais novos e dão controle preciso sobre as permissões.
  • Defina uma validade. 90 dias é um bom equilíbrio. Quanto mais curta, mais seguro.
  • Faça rotação com regularidade. Apague tokens antigos e crie novos a cada poucos meses.
  • Comece em somente leitura. Deixe ligado por padrão. Só acrescente permissões de escrita se o Claude realmente precisar.
  • Limite o acesso a repositórios. Use “Only select repositories” em vez de dar ao Claude acesso a todos os seus repositórios.
  • Nunca deixe tokens escritos no controle de versão. Use variáveis de ambiente ou arquivos de configuração separados que você não sobe.
  • Audite os seus tokens. Entre em GitHub Settings → Developer settings → Personal access tokens e revise quais continuam ativos. Apague o que não estiver usando.

Perguntas frequentes

Posso usar o mesmo token em várias máquinas?

Sim. Um token está ligado à sua conta do GitHub, não a uma máquina específica. Você pode usar o mesmo no notebook, no desktop e no servidor. Dito isso, se uma máquina for comprometida, quem atacar tem acesso a todas as que usam aquele token. Em ambientes de alta segurança, considere um token diferente por máquina ou por ambiente (desenvolvimento, homologação, produção).

E se eu quiser que o Claude altere repositórios?

Crie um segundo token com permissões de escrita (por exemplo Contents → Read and write e Pull requests → Read and write) e use-o nas tarefas que exigem alterações. Guarde o token somente leitura para navegar e explorar. Assim você reduz o raio de dano se o token de escrita vazar.

É seguro usar MCP com código fechado?

Em geral sim, com ressalvas. O seu código fica no seu repositório; o Claude lê e processa no servidor (da Anthropic). Confira a política de privacidade da Anthropic e as regras de governança de dados da sua empresa. Se o seu código for muito sensível, considere rodar o Claude localmente ou em um ambiente isolado. Em repositórios privados do GitHub, o token dá acesso apenas aos repositórios que você autorizou explicitamente.

Uso o servidor MCP oficial do GitHub ou construo o meu?

Use o oficial do GitHub. Ele é mantido, testado e atualizado com recursos novos com regularidade. Construir o seu só faz sentido se você precisa de lógica sob medida ou de integração com sistemas internos que o servidor do GitHub não suporta.

O que acontece se o meu token vencer?

O Claude vai receber erros de autenticação ao tentar usar o GitHub. Olhe a mensagem de erro — normalmente ela diz que o token é inválido ou venceu. Gere um token novo, atualize a sua configuração e reinicie o Claude.