GitHub MCP Server

Servidor MCP (Model Context Protocol) customizado, escrito em TypeScript, que conecta o Claude à API REST do GitHub.

O que ele faz

Expõe 6 ferramentas (tools) que o Claude pode chamar:

Tool	Descrição
list_repos	Lista repositórios do usuário autenticado
get_repo	Detalhes de um repositório específico
list_issues	Lista issues de um repositório
create_issue	Cria uma issue nova
get_file_content	Lê o conteúdo de um arquivo do repositório
search_code	Busca código no GitHub

1. Gerar um GitHub Personal Access Token

1. Acesse GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens
2. Crie um token com permissões mínimas necessárias:
   • Contents: Read (para get_file_content)
   • Issues: Read and write (para list_issues/create_issue)
   • Metadata: Read (obrigatório sempre)
3. Copie o token gerado (começa com github_pat_...)

Dica de segurança: nunca commite o token no repositório. Use variável de ambiente.

2. Instalar e buildar

npm install
npm run build

Isso gera build/index.js, que é o executável do servidor (comunica via stdio, protocolo padrão do MCP).

3. Testar localmente (opcional, sem Claude)

export GITHUB_PERSONAL_ACCESS_TOKEN="seu_token_aqui"
npm start

Se aparecer GitHub MCP server rodando via stdio. no stderr, está funcionando. Para testar as tools interativamente, use o MCP Inspector:

npx @modelcontextprotocol/inspector node build/index.js

4. Conectar ao Claude Desktop

Edite o arquivo de configuração do Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Adicione:

{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["/caminho/absoluto/para/github-mcp-server/build/index.js"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "seu_token_aqui"
      }
    }
  }
}

Reinicie o Claude Desktop. As ferramentas do GitHub devem aparecer no ícone de ferramentas (🔨) da conversa.

5. Próximos passos (ideias para expandir e turbinar o portfólio)

• Adicionar tools de escrita: create_pull_request, merge_pull_request, create_branch
• Adicionar paginação real (cursor-based) em vez de só per_page
• Rate limiting e cache (o GitHub limita a 5000 req/h autenticado)
• Testes automatizados com Vitest/Jest
• CI com GitHub Actions rodando lint + testes + build a cada push
• Publicar como pacote npm (npx github-mcp-server)
• Dockerizar o servidor (bom gancho pra conectar com seus outros projetos DevOps)

Estrutura do projeto

github-mcp-server/
├── src/
│   └── index.ts      # lógica do servidor e definição das tools
├── build/             # gerado pelo `npm run build`
├── package.json
├── tsconfig.json
└── README.md