Tutorial do conector do Claude Code: faça triagem de repositórios do GitHub em 20 minutos

Neste tutorial, vou mostrar como conectar o Claude Code ao GitHub usando um conector do Claude (baseado no Model Context Protocol) e usá-lo para fazer a triagem ponta a ponta de um repositório open source. 

O fluxo de trabalho não faz clone de nada, não precisa de vector store e não toca em nenhuma linha do repositório-alvo. Em vez disso, o Claude Code lê as issues pelo conector e grava artefatos no seu sistema de arquivos local para você revisar antes de decidir o que (se for o caso) publicar.

Ao final deste tutorial, você terá:

• Uma configuração funcional do Claude Code e do GitHub MCP com um token somente leitura,
• Alguns prompts reutilizáveis que você pode apontar para qualquer repositório público,
• Um artefato de triagem completo para langchain-ai/langchain para você comparar.

O que é o conector GitHub do Claude Code (MCP)?

Claude Code é o agente de código no terminal da Anthropic. 

De fábrica, ele já tem acesso ao seu sistema de arquivos, shell e git. Os conectores do Claude Code o estendem para alcançar contextos externos — como issues do GitHub, tickets do Linear, mensagens do Slack, queries no Postgres e por aí vai — que o terminal sozinho não alcança.

O protocolo do conector se chama MCP (Model Context Protocol), um padrão aberto para expor ferramentas e dados a agentes de LLM. 

A Anthropic mantém um diretório de conectores prontos para uso, e você também pode escrever os seus ou se conectar a servidores MCP de terceiros.

Para este tutorial, vamos usar o GitHub MCP server oficial, que roda localmente via Docker. Algumas ideias centrais por trás da configuração:

• Roda como um contêiner Docker local, sem intermediários na nuvem, então as credenciais ficam na sua máquina.
• Autentica com um GitHub Personal Access Token (PAT) padrão, então não é preciso registrar um app OAuth.
• Suporta permissões com escopo, como um PAT sem escopos, que dá acesso somente leitura a repositórios públicos — ou seja, gravações são impossíveis no nível da API do GitHub.
• É exposto ao Claude Code via o comando claude mcp add, e as ferramentas ficam disponíveis em toda sessão.

A triagem de open source é intensiva em leitura, demanda julgamento e é barata de errar. 

Ler 50 issues e agrupá-las é maçante para uma pessoa, mas combina bem com um modelo que consegue manter tudo em contexto ao mesmo tempo. 

Além disso, escrevemos as saídas primeiro como arquivos locais; um agrupamento ruim ou um rascunho desajeitado não custam nada, e você pega isso na revisão.

Tutorial do conector GitHub do Claude Code: construa uma triagem para langchain-ai/langchain

Nesta seção, vamos configurar o conector do GitHub no Claude Code e rodar quatro prompts de triagem no langchain-ai/langchain. É um repositório grande de ML com um rastreador de issues realmente bagunçado. Em alto nível, vamos construir:

• Conectar o Claude Code ao GitHub via o servidor MCP oficial rodando no Docker,
• Usar um PAT sem escopos para que o conector seja somente leitura por construção,
• Executar prompts de triagem que salvam resultados em arquivos locais,
• Revisar as saídas, incluindo casos em que o Claude se recusou a agrupar issues como duplicadas.

Vamos construir isso passo a passo.

Passo 1: instale os pré-requisitos para o Claude Code e o Docker

Antes de configurar o conector, você vai precisar de três coisas:

• Claude Code: você pode instalar pelo guia oficial da Anthropic,
• Docker Desktop: o servidor GitHub MCP oficial roda em um contêiner, então o Docker precisa estar instalado e em execução,
• Uma conta no GitHub: necessária para gerar o PAT no próximo passo.

Com tudo pronto, verifique se o Docker está rodando:

docker info | head -5

Se o Docker não estiver instalado ou o daemon não estiver ativo, você verá o erro "Cannot connect to the Docker daemon". No macOS, abra o Docker Desktop com:

open -a Docker

O Docker Desktop leva de 15 a 60 segundos para ficar totalmente pronto, e o docker info continuará dando erro nesse intervalo. Em vez de checar manualmente, use um one-liner de espera que faz polling até o daemon subir:

until 

docker info >/dev/null 2>&1; do sleep 2; echo "waiting..."; done && echo "Docker ready"

Quando aparecer Docker ready, pode seguir.

Passo 2: crie um token do GitHub somente leitura

Com o Docker pronto, acesse github.com/settings/tokens e gere um novo token clássico.

Observação: deixe todos os escopos desmarcados. Um token sem escopos ainda consegue ler repositórios públicos via a API do GitHub, que é tudo o que nosso agente precisa. Sem nenhum escopo selecionado, o token não consegue escrever, modificar ou apagar nada no GitHub, não importa o que pedirmos ao Claude. Essa é uma garantia rígida imposta pelo GitHub, não uma promessa sobre o comportamento do agente.

Copie e salve o token imediatamente após gerá-lo e então exporte no seu shell:

export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_your_token_here"

Se você já estiver dentro de uma sessão do Claude Code, pode ficar tentado a usar o prefixo ! para rodar o comando de export direto no seu shell (por exemplo, ! export GITHUB_PERSONAL_ACCESS_TOKEN="..."). 

Porém, como ! abre um subshell temporário, a variável vai sumir assim que o comando terminar, e o Claude não vai enxergá-la.

Para definir o token com segurança sem colá-lo no prompt do modelo, você tem duas opções:

1. Digite /exit para sair do Claude, rode o comando de export no seu terminal normal e reinicie o claude.
2. Ou salve o token em um arquivo .env local no seu diretório de trabalho, que o Claude Code lê automaticamente ao iniciar.

Verifique que ambos os pré-requisitos estão prontos sem exibir o token em si:

docker info | head -3
echo "Token set: ${GITHUB_PERSONAL_ACCESS_TOKEN:+yes}"

O segundo comando imprime Token set: yes se a variável existir e Token set: (nada após os dois-pontos) se estiver vazia. 

Isso é mais seguro do que exibir o token diretamente porque não há chance de ele ir parar em texto plano no histórico do seu shell.

Passo 3: registre o conector do GitHub no Claude Code

O servidor GitHub MCP oficial é distribuído como uma imagem Docker. 

Nós o registramos no Claude Code usando claude mcp add:

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

As duas flags -e não são erro de digitação::

• A primeira -e (antes do --) define uma variável de ambiente para o processo MCP que o Claude Code dispara,
• A segunda -e (dentro dos argumentos do docker run) instrui o Docker a encaminhar essa variável para dentro do contêiner.

Se você esquecer uma delas e o contêiner iniciar com um token vazio, a autenticação na API do GitHub vai falhar.

Para verificar se o conector foi registrado com sucesso:

claude mcp list

Você deve ver:

github — docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server —  Connected

Se aparecer Failed to connect, as duas causas mais comuns são o Docker não estar rodando ou o GITHUB_PERSONAL_ACCESS_TOKEN não ter sido exportado no mesmo shell em que você executou claude mcp add.

Passo 4: teste rápido da conexão

Agora que o token do GitHub está definido, crie um diretório de trabalho e abra o CLI do Claude Code:

mkdir demo && cd demo
claude

O comando claude inicia uma sessão interativa no diretório atual. 

Qualquer arquivo que o Claude escrever durante a triagem vai parar aqui. 

Depois, faça uma pergunta simples somente leitura para confirmar que o conector está sendo usado:

Using the GitHub MCP connector, fetch the 5 most recently updated open issues in langchain-ai/langchain. Just list titles and numbers.

Na primeira vez que o Claude Code usar uma ferramenta do GitHub, ele vai pedir aprovação. 

Aprove ferramentas somente leitura como list_issues, get_issue, search_issues etc. 

Se o Claude recorrer a curl contra a API pública do GitHub em vez de usar as ferramentas MCP, o conector não foi carregado. Nesse caso, saia da sessão e reinicie.

Uma execução bem-sucedida retorna algo como:

Quando você vir números reais de issues chegando via MCP, estaremos prontos para rodar a triagem de verdade.

Passo 5: gere um resumo do backlog

A tarefa de aquecimento é somente leitura. Agora, queremos um mapa do que há no rastreador de issues antes de qualquer ação.

Prompt:
Using the GitHub MCP connector, pull the 50 most recently updated open issues from langchain-ai/langchain. 
Read their titles, bodies, and labels. Group them by likely area — bugs, feature requests, documentation, questions, and "needs more info." 
For each group, give me a count and 3-5 representative issue numbers with a one-line reason. Save as backlog-summary.md in the current directory.

O Claude Code busca as issues via o conector, lê tudo e escreve um arquivo markdown agrupando por área com números de issues representativos. Só esse arquivo já é útil: um maintainer pode bater o olho em 60 segundos e saber como vai ser a semana.

Passo 6: marque candidatos a duplicadas

A detecção de duplicadas é onde um agente mostra seu valor. 

Ler 50 issues de ponta a ponta e agrupar por problema de base é cansativo para uma pessoa, mas um modelo consegue manter todas em contexto e identificar sobreposições que uma busca por palavras-chave deixaria passar.

Prompt:
From the same 50 issues you already pulled, identify clusters of likely duplicates: issues describing the same underlying problem, even if titles differ. For each cluster, output issue numbers, a one-sentence shared-problem description, and confidence (high/medium/low). Save as duplicate-candidates.md.

Aqui está o que o Claude realmente produziu na minha execução:

A parte mais interessante dessa saída são os clusters 2 a 4. 

Um detector ingênuo baseado em palavras-chave teria fechado todos os quatro clusters como duplicados. 

O Claude se recusou explicitamente a chamá-los de duplicados. 

Ele marcou como clusters de componentes do mesmo subsistema, com causas raiz distintas, e me disse quais fechar de fato (apenas o Cluster 1) versus quais triagar em conjunto, mas manter abertos.

Esse é o comportamento que você espera de uma pessoa cuidadosa fazendo triagem — e é exatamente por isso que o padrão de escrever em arquivos locais e revisar vale o passo extra. 

Se tivéssemos ligado isso direto na API do GitHub e fechado automaticamente tudo que o Claude sinalizou, teríamos fechado três bugs reais.

Passo 7: revise e só então decida o que publicar

Esse é o ponto central do padrão de arquivos locais. 

Antes de qualquer coisa tocar o GitHub, confira cada arquivo .md salvo pelo Claude e veja se os agrupamentos batem com a sua intuição. 

Os clusters de alta confiança realmente parecem duplicadas? Leia 2-3 respostas de rascunho e veja se soam como você.

Se quiser realmente postar os comentários ou aplicar labels, você tem duas opções:

• Manual: você mesmo pode colar os rascunhos no GitHub. Para uma sessão pontual de triagem em um repositório de terceiros, isso é ok e muitas vezes a melhor escolha.
• Autorizar gravações em um repositório seu: gere um PAT separado com escopo repo, adicione-o como uma entrada de conector distinta (por exemplo, github-write) e rode novamente os prompts pedindo para o Claude aplicar labels e postar comentários. O Claude Code vai solicitar aprovação na primeira vez que cada ferramenta de escrita for usada.

A principal medida de segurança no caminho de escrita é manter tokens de leitura e de escrita separados. 

Conclusão

Neste tutorial, mostrei como conectar o Claude Code ao GitHub via MCP e usá-lo para fazer triagem ponta a ponta de um repositório open source real. 

Em vez de construir um bot customizado para o GitHub ou configurar webhooks, o fluxo lê issues pelo servidor GitHub MCP oficial, escreve quatro artefatos de triagem como arquivos locais e permite que você revise tudo antes de decidir o que publicar.

A lição mais ampla é que conectores transformam o Claude Code de um agente de código em uma ferramenta que consegue ler suas ferramentas e preparar trabalho para você revisar. 

O padrão ideal é manter esse trabalho local até você vê-lo e, quando confiar no processo, permitir que o agente tome ações seletivamente onde o custo de um erro é baixo.

Daqui, você pode estender o projeto de várias formas:

• Adicionar conectores com permissão de escrita em repositórios seus para que labels e comentários sejam aplicados automaticamente após a revisão,
• Encadear conectores do Linear ou Slack para sincronizar decisões de triagem com o fluxo do seu time,
• Transformar os prompts em um job de CI agendado que cria um PR semanal de triagem,
• Ou generalizar os prompts acima em um comando de barra do Claude Code reutilizável que funcione com qualquer URL de repositório.