Como conectar o GitHub MCP com o Claude Code: guia passo a passo (2026)

O que é o GitHub MCP com o Claude Code (e o que ele faz)?

O servidor GitHub MCP é a ponte que permite ao Claude Code ler e agir no GitHub diretamente por linguagem natural - sem sair do terminal, sem copiar e colar na mão. O MCP (Model Context Protocol) é um padrão aberto que conecta a IA a ferramentas externas; se o conceito é novo para você, comece por o que é o MCP e como ele funciona.

Depois de conectado, você pode pedir ao Claude para fazer coisas como: listar seus repositórios e issues abertas, criar uma nova issue, abrir um pull request, revisar o código de um PR, buscar código por descrição ou ler um arquivo dentro de um repositório. Em vez de abrir o navegador e clicar pelo GitHub, você digita uma frase e o Claude chama a API do GitHub por você. É isso que o diferencia de disparar comandos gh individuais: o Claude entende o contexto da sua sessão inteira e escolhe a ferramenta certa sozinho.

Um exemplo real: enquanto corrige um bug, você pode dizer "encontre a issue relacionada a este erro de timeout e resuma os comentários", e o Claude vai consultar o GitHub, ler a issue e responder ali mesmo no terminal - sem trocar de janela. Depois de aplicar a correção, você continua com "abra um PR a partir da branch atual e referencie aquela issue". Toda essa sequência de ações acontece em uma única conversa, mantendo o contexto do código em que você está trabalhando. É por isso que muitos devs deixam o GitHub MCP conectado como ferramenta padrão, em vez de ligar e desligar toda hora.

Antes de começar (checklist)

Antes de adicionar o servidor, faça uma verificação rápida do seguinte:

• O Claude Code está instalado e roda no seu terminal - se não, veja como instalar o Claude Code.
• Uma conta no GitHub com acesso aos repositórios em que você quer que o Claude trabalhe.
• Escolha um método de conexão: HTTP remoto (recomendado - rápido, nada para instalar) ou Docker (se você quiser o servidor rodando localmente na sua máquina). Para a maioria das pessoas, o HTTP remoto já basta.
• Se você escolher o Docker: instale o Docker Desktop e deixe-o aberto antes de adicionar o servidor.

Este guia inteiro leva cerca de 5 a 10 minutos se você seguir pelo caminho do HTTP remoto.

O jeito mais rápido em 2026: instalar pelo marketplace oficial de plugins

Em 2026, o Claude Code já vem com um marketplace oficial de plugins embutido. O jeito mais rápido de colocar o GitHub MCP para rodar é digitar isto dentro de uma sessão:

/plugin install github@claude-plugins-official

O marketplace claude-plugins-official se registra sozinho na primeira vez que você abre o Claude Code de forma interativa - se ele não estiver lá, adicione manualmente com /plugin marketplace add anthropics/claude-plugins-official. Esse plugin já traz um servidor GitHub MCP pré-configurado, e você ainda escolhe um escopo (User/Project/Local) que espelha a flag -s do Passo 2 abaixo. Confirme que conectou com /mcp ou /plugin list --enabled.

⚠️ Ainda não confirmado: se instalar pelo plugin ainda pede para você colar um PAT, ou se dispara automaticamente um login por OAuth/device flow - a documentação oficial não deixa isso claro, e eu vou atualizar esta seção assim que verificar direto.

Contrapartida: mais rápido, mas com controle de escopo e permissões menos fino do que o caminho manual de 4 passos abaixo - para uso em equipe ou produção, o caminho manual ainda é o padrão mais seguro, já que você escolhe exatamente as permissões de que precisa.

Quer ver outros plugins e servidores MCP além do GitHub? Veja os melhores plugins e MCP do Claude Code para 2026 (o link entra no ar quando o artigo for publicado).

Passo 1 - Crie um GitHub Personal Access Token (PAT)

O GitHub MCP precisa de um token para chamar a API em seu nome. O GitHub tem dois tipos de token: classic (permissões amplas por escopo) e fine-grained (permissões por repositório). Use um token fine-grained, porque você pode limitá-lo exatamente aos repositórios e permissões de que precisa, o que reduz o estrago caso o token vaze:

1. Vá ao GitHub -> seu avatar -> Settings.
2. Role até o fim do menu à esquerda e escolha Developer settings.
3. Escolha Personal access tokens -> Fine-grained tokens -> Generate new token.
4. Dê um nome (por exemplo claude-code-mcp) e defina uma expiração sensata (30 a 90 dias).
5. Em Repository access, escolha Only select repositories e marque apenas os repositórios que você quer que o Claude toque.
6. Em Permissions -> Repository permissions, conceda o mínimo necessário: Contents (ler/gravar arquivos), Issues e Pull requests. Se você trabalha com uma organização, adicione read:org.
7. Clique em Generate token e copie o token na hora.

Aviso de segurança: o GitHub mostra o token apenas uma vez. Copie e guarde em um lugar seguro (um gerenciador de senhas). NÃO faça commit do token em um repositório e não o cole em nenhum arquivo versionado pelo git. Só conceda acesso de escrita quando você realmente quiser que o Claude crie ou edite conteúdo por conta própria.

Passo 2 - Adicione o servidor GitHub MCP (recomendado: HTTP remoto)

Este é o jeito mais rápido e não precisa de Docker. Abra um terminal, troque YOUR_PAT pelo token que você acabou de criar e rode:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ -H "Authorization: Bearer YOUR_PAT"

Se você prefere uma configuração em JSON (prática quando você quer deixá-la pronta para copiar), use esta alternativa:

claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_PAT"}}'

Escolha o escopo da configuração com a flag -s:

• -s local (padrão): vale só para esta máquina, no diretório atual.
• -s user: compartilhado entre todos os seus projetos - útil quando você quer o GitHub MCP sempre disponível e o token fora de qualquer repositório.
• -s project: salvo em .mcp.json e compartilhado com o time inteiro pelo git. Conveniente para equipes, mas cuidado: nunca deixe um token real cair neste arquivo.

Por exemplo, para compartilhar em todos os projetos, adicione -s user ao final do comando claude mcp add acima. A sintaxe completa de claude mcp add está na documentação oficial de MCP do Claude Code (atualizada em 2026).

Uma observação sobre OAuth: em 08/2026, o fluxo OAuth ainda não é totalmente suportado para o GitHub MCP remoto no Claude Code, então usar um PAT como mostrado acima é a abordagem mais confiável.

Passo 3 (alternativa) - Rode o GitHub MCP com Docker (local)

Se você quer o servidor rodando inteiramente na sua máquina (digamos, para controle total ou para rodá-lo em um ambiente isolado), use a imagem oficial ghcr.io/github/github-mcp-server. Garanta que o Docker Desktop esteja aberto e então rode:

claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_PAT -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

Quando você deve escolher o Docker em vez do HTTP remoto? Aqui vai uma comparação rápida:

Não use o pacote npm descontinuado

Este é o erro mais comum. Muitos guias antigos (em todos os idiomas) ainda mandam você instalar o @modelcontextprotocol/server-github via npm. Aquele pacote da comunidade foi descontinuado lá em 04/2025 - seguir esse caminho leva a um servidor que não conecta ou a erros obscuros. A abordagem correta em 2026 é HTTP remoto ou a imagem Docker oficial do repositório github/github-mcp-server (a fonte oficial do GitHub, atualizada em 2026).

Passo 4 - Verifique e experimente

Depois de adicionar o servidor, confirme que ele aparece como "Connected":

claude mcp list

Você deve ver github com status de conectado. Em seguida, abra o Claude Code e digite:

/mcp

O comando /mcp lista todas as ferramentas do GitHub agora disponíveis. Agora experimente alguns prompts reais:

• "Liste meus repositórios do GitHub."
• "Crie uma issue em owner/repo com o título: Improve the setup docs."
• "Resuma os pull requests abertos neste repositório."

Se o Claude retornar os dados certos e conseguir criar uma issue, está tudo conectado.

Solução de problemas comuns

A maioria dos problemas de conexão do GitHub MCP se resume a três causas: um token errado ou permissões faltando, usar o método de instalação antigo por engano, ou não reiniciar o Claude Code depois de adicionar o servidor. Se algo estiver estranho, compare o seu sintoma com a tabela abaixo:

Dica geral: na dúvida, rode claude mcp remove github e adicione de novo do zero - isso resolve a maioria dos problemas de configuração.

Segurança e privilégio mínimo (read-only, toolsets)

Dar a um agente acesso de escrita ao GitHub é conveniente, mas existe risco real: um prompt vago pode fazer o Claude criar uma issue ou um PR que você não pretendia, e um token vazado com permissões amplas demais afetaria muitos repositórios. Algumas regras para se manter em segurança:

• Conceda um token mínimo: selecione só os repositórios de que precisa e só as permissões que usa.
• Nunca faça commit de tokens: prefira -s user para o token ficar fora de qualquer repositório; se precisar mesmo usar -s project, passe o token por uma variável de ambiente em vez de escrevê-lo em texto puro.
• Use read-only quando você só precisa ler: o servidor GitHub MCP suporta um modo read-only e permite ativar ou desativar toolsets individuais - limite para que o Claude só possa ler, e não gravar, quando você só quer revisar ou consultar algo.
• Defina uma expiração curta para o token e revogue-o quando terminar.

Sendo bem honesta: nenhuma configuração é perfeitamente segura depois que você entrega acesso de escrita a uma IA - mantenha o token com escopo bem apertado e confira duas vezes as ações importantes.

Próximo passo: automatize seu fluxo de git com o Claude Code

Assim que o GitHub MCP estiver rodando, o passo natural seguinte é deixar o Claude cuidar de todo o ciclo de vida de uma mudança: criar uma branch, commitar seguindo um padrão, abrir um PR e revisar. É esse o tema de automatizar seu fluxo de git com o Claude Code (o link entra no ar quando o artigo for publicado).

Perguntas frequentes (FAQ)

O GitHub MCP é gratuito?

O servidor GitHub MCP em si (tanto o HTTP remoto quanto a imagem Docker oficial) é gratuito. Você só precisa de uma conta no GitHub e um Personal Access Token. As ações ainda contam para os limites normais de taxa da API do GitHub da sua conta.

O Docker é obrigatório?

Não. O método recomendado é o HTTP remoto - só um comando claude mcp add --transport http, sem Docker. O Docker só é necessário se você quiser o servidor rodando localmente na sua máquina.

De quais escopos o PAT precisa?

Com um token fine-grained, conceda no mínimo Contents, Issues e Pull requests nos repositórios específicos que você quer usar. Adicione read:org se você trabalha dentro de uma organização. Não conceda mais do que o necessário.

Como eu removo o servidor GitHub MCP?

Rode claude mcp remove github. Se o servidor foi adicionado sob um escopo diferente, especifique esse escopo de novo (por exemplo -s user) ao removê-lo.

Qual a diferença em relação à CLI gh?

O gh é uma ferramenta de linha de comando em que você digita cada comando manualmente. O GitHub MCP deixa o Claude chamar a API do GitHub com base no contexto da conversa - você faz um pedido em linguagem natural, o Claude escolhe a ferramenta e a executa, e pode encadear isso com outros passos na mesma sessão.

O OAuth já funciona?

Em 08/2026, o OAuth ainda não é totalmente suportado para o GitHub MCP remoto no Claude Code, então um PAT continua sendo o jeito confiável e recomendado de conectar.

Conclusão

Em apenas quatro passos - criar um PAT -> adicionar o servidor por HTTP remoto -> verificar com claude mcp list e /mcp -> experimentar - você deu ao Claude Code a capacidade de ler e agir no GitHub por linguagem natural. Os pontos-chave: use HTTP remoto ou a imagem Docker oficial, evite o pacote npm descontinuado e mantenha seu token com escopo bem apertado e fora de qualquer repositório. Quer ainda mais rápido e topa abrir mão de um pouco de controle de escopo? Vale testar o comando /plugin install github@claude-plugins-official acima. Para entender melhor os fundamentos, leia o que é o MCP e como ele funciona; para ir mais fundo na automação, veja o fluxo de git com o Claude Code (link quando estiver no ar). Precisa do comando /mcp e de outros slash commands? Veja os slash commands no Claude Code.