GitHub MCP Server

Integre funcionalidades do GitHub em assistentes de IA usando a CLI do GitHub.

GitHub
8
Experimente este MCPPatrocinado

Documentação

GitHub MCP Server

Um servidor Model Context Protocol (MCP) baseado em Spring Boot que fornece ferramentas de integração com GitHub para assistentes de IA como o Claude Desktop.

Visão Geral

Este servidor implementa o Model Context Protocol para expor operações do GitHub como ferramentas que podem ser usadas por clientes MCP. Ele utiliza o GitHub CLI (gh) para realizar diversas operações do GitHub, incluindo gerenciamento de repositórios, rastreamento de issues, gerenciamento de pull requests e muito mais. Isso oferece uma alternativa leve ao servidor MCP oficial do GitHub que não requer Docker.

Início Rápido para Claude Desktop

Para usar este servidor com o Claude Desktop, adicione o seguinte ao seu arquivo de configuração do Claude:

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

{
  "mcpServers": {
    "github": {
      "command": "java",
      "args": ["-jar", "/path/to/gh_mcp_server/build/libs/gh_mcp_server.jar"],
      "env": {}
    }
  }
}

Substitua /path/to/gh_mcp_server pelo caminho real do diretório do seu projeto.

Recursos

Operações de Repositório

  • Listar repositórios do usuário autenticado
  • Pesquisar repositórios no GitHub
  • Obter informações detalhadas do repositório
  • Listar branches em um repositório
  • Criar novos branches
  • Obter conteúdo de arquivos de repositórios
  • Obter histórico de commits

Gerenciamento de Issues

  • Listar issues (abertas, fechadas ou todas)
  • Obter informações detalhadas de issues
  • Criar novas issues
  • Fechar issues
  • Adicionar comentários a issues
  • Editar título e corpo de issues

Gerenciamento de Pull Requests

  • Listar pull requests
  • Obter informações detalhadas de pull requests
  • Criar novos pull requests
  • Mesclar pull requests (merge, squash ou rebase)
  • Fechar pull requests
  • Adicionar comentários a pull requests

Workflows e Actions

  • Listar workflows em um repositório
  • Listar execuções de workflows com filtros opcionais
  • Visualizar informações detalhadas de execuções de workflows

Gerenciamento de Releases

  • Listar releases
  • Visualizar detalhes de releases
  • Criar novos releases (com opções de rascunho/pré-lançamento)

Operações de Usuário

  • Obter detalhes do usuário autenticado

Pré-requisitos

  • Java 21 ou superior - Utiliza recursos modernos do Java (virtual threads, records, pattern matching)
  • GitHub CLI (gh) - Deve estar instalado e autenticado
  • Gradle - Wrapper incluído no projeto

Por que Usar Este Servidor MCP?

  • 🚀 Leve: Sem necessidade de Docker, implementação pura em Java
  • 🔧 Abrangente: 26 operações do GitHub cobrindo fluxos de trabalho completos
  • ⚡ Rápido: Integração direta com GitHub CLI com respostas JSON otimizadas
  • 🧪 Bem Testado: Mais de 75 casos de teste garantindo confiabilidade
  • 🛡️ Seguro: Utiliza a autenticação existente do GitHub CLI

Configuração

  1. Instalar GitHub CLI

    # macOS
brew install gh

# or download from https://cli.github.com/

  2. Autenticar com GitHub

    gh auth login

  3. Clonar e construir o projeto

    git clone <repository-url>
cd gh_mcp_server
./gradlew build

    Nota: A construção cria automaticamente um symlink independente de versão gh_mcp_server.jar → gh_mcp_server-1.0.0.jar

  4. Configurar Claude Desktop

    Após a construção, configure o Claude para usar este servidor MCP. Você tem duas opções:

    Opção A: Usando o arquivo JAR (Recomendado)

    {
  "mcpServers": {
    "github": {
      "command": "java",
      "args": ["-jar", "/path/to/gh_mcp_server/build/libs/gh_mcp_server.jar"],
      "env": {}
    }
  }
}

    Nota: Um symlink gh_mcp_server.jar aponta para a versão atual (gh_mcp_server-1.0.0.jar). Isso fornece implantação independente de versão. Para implantação específica de versão, use o nome completo do arquivo versionado.

    Opção B: Usando Gradle

    {
  "mcpServers": {
    "github": {
      "command": "./gradlew",
      "args": ["bootRun"],
      "cwd": "/path/to/gh_mcp_server",
      "env": {}
    }
  }
}

  5. Reiniciar Claude Desktop para carregar a nova configuração do servidor

Exemplos de Uso

Após configurar o Claude Desktop, você pode usar linguagem natural para interagir com o GitHub:

Gerenciamento de Repositórios

  • "Liste meus repositórios" → Mostra seus repositórios com detalhes
  • "Liste meus repositórios privados" → Filtra por visibilidade (público/privado/interno)
  • "Pesquise repositórios Spring Boot com mais de 1000 estrelas"
  • "Mostre-me detalhes sobre o repositório microsoft/vscode"
  • "Obtenha os últimos 5 commits do meu repositório de projeto"
  • "Quais branches existem no meu repositório de projeto?"

Rastreamento de Issues

  • "Liste issues abertas no meu projeto" → Lista issues abertas atuais
  • "Mostre-me detalhes da issue #123" → Obtém informações específicas da issue
  • "Crie uma nova issue intitulada 'Bug: Falha no login' com descrição..."
  • "Feche a issue #123 e adicione um comentário 'Corrigido na versão mais recente'"

Gerenciamento de Pull Requests

  • "Liste todos os pull requests no repositório kubernetes/kubernetes"
  • "Mostre-me detalhes do PR #456"
  • "Crie um pull request do meu feature-branch para main"
  • "Mescle o PR #789 usando estratégia squash"

CI/CD e Releases

  • "Mostre-me todos os workflows neste repositório" → Lista GitHub Actions
  • "Qual é o status das execuções recentes de workflows?"
  • "Liste releases para o repositório golang/go"
  • "Crie um novo release v2.1.0 como rascunho"

Operações de Arquivos

  • "Obtenha o conteúdo do package.json do meu projeto"
  • "Mostre-me o arquivo README do branch main"

Verificação

Se o servidor falhar ao iniciar, verifique se:

  • Java 21+ está instalado e no seu PATH
  • GitHub CLI está instalado e autenticado (gh auth status)
  • O caminho do arquivo JAR na configuração está correto
  • Claude Desktop foi reiniciado

Testando o Servidor

Para testar o servidor independentemente (sem Claude):

./gradlew bootRun

O servidor iniciará no modo STDIO e aguardará mensagens do protocolo MCP. No entanto, para uso normal, o servidor deve ser configurado para executar automaticamente pelo Claude Desktop, conforme mostrado acima.

Comandos de Desenvolvimento

# Build the project and run all tests
./gradlew build

# Run tests (command syntax validation only)
./gradlew test

# Run tests including GitHub CLI integration tests
./gradlew test -Dtest.gh.integration=true

# Format code with Spotless (Google Java Format)
./gradlew spotlessApply

# Check code formatting without applying changes
./gradlew spotlessCheck

# Clean build artifacts
./gradlew clean

# Run the server locally for testing
./gradlew bootRun

Cobertura de Testes

O projeto inclui cobertura abrangente de testes:

  • Mais de 75 casos de teste validando todas as 26 operações do GitHub
  • Testes de sintaxe de comandos - Verificam a construção exata do comando gh
  • Testes de casos extremos - Lidam com caracteres especiais, Unicode, valores nulos
  • Testes de integração - Execução opcional do GitHub CLI real
  • Testes de tratamento de erros - Validam modos de falha graciosa

Consulte src/test/java/com/kousenit/gh_mcp_server/TEST_README.md para documentação detalhada de testes.

Configuração

O servidor usa a configuração padrão do Spring Boot. Você pode personalizar as configurações em src/main/resources/application.properties.

Principais Opções de Configuração

  • github.defaultBranch - Nome do branch padrão para operações (padrão: main)
  • spring.threads.virtual.enabled - Ativar virtual threads para melhor desempenho (padrão: true)
  • O servidor MCP executa no modo STDIO para integração com CLI

Operações Disponíveis (26 no Total)

Operações de Repositório

  • listRepositories - Lista repositórios do usuário com filtro opcional de visibilidade (público/privado/interno)
  • searchRepositories - Pesquisa repositórios no GitHub
  • getRepository - Obtém informações detalhadas do repositório
  • getCommitHistory - Obtém histórico de commits do repositório com limite configurável
  • listBranches - Lista branches do repositório
  • createBranch - Cria um novo branch

Gerenciamento de Issues

  • listIssues - Lista issues no repositório
  • getIssue - Obtém detalhes específicos de uma issue
  • createIssue - Cria nova issue
  • closeIssue - Fecha uma issue
  • commentOnIssue - Adiciona comentário a uma issue
  • editIssue - Edita título/corpo de uma issue

Gerenciamento de Pull Requests

  • listPullRequests - Lista pull requests
  • getPullRequest - Obtém detalhes do PR
  • createPullRequest - Cria novo pull request
  • mergePullRequest - Mescla PR (merge/squash/rebase)
  • closePullRequest - Fecha pull request
  • commentOnPullRequest - Adiciona comentário ao PR

Workflow e CI/CD

  • listWorkflows - Lista workflows do repositório
  • listWorkflowRuns - Lista execuções de workflows com filtros
  • getWorkflowRun - Obtém detalhes da execução do workflow

Gerenciamento de Releases

  • listReleases - Lista releases do repositório
  • getRelease - Obtém detalhes do release
  • createRelease - Cria novo release (opções de rascunho/pré-lançamento)

Operações de Arquivos e Usuário

  • getFileContents - Obtém conteúdo de arquivo do repositório
  • getMe - Obtém detalhes do usuário autenticado

Todas as operações retornam respostas JSON otimizadas e suportam tratamento abrangente de erros.

Solução de Problemas

Problemas Comuns

"gh: comando não encontrado"

  • Instale o GitHub CLI em https://cli.github.com/
  • Certifique-se de que gh está no PATH do seu sistema
  • Teste com gh --version

Erros de autenticação

  • Execute gh auth login para autenticar
  • Verifique o status com gh auth status
  • Certifique-se de ter acesso aos repositórios que está tentando acessar

Falhas na inicialização do servidor

  • Verifique se Java 21+ está instalado: java --version
  • Verifique o caminho do arquivo JAR na configuração do Claude
  • Procure mensagens de erro nos logs do Claude Desktop
  • Certifique-se de que o servidor não está em execução em outra instância

Tempos limite de comandos

  • Repositórios grandes ou redes lentas podem causar tempos limite
  • O tempo limite padrão é de 30 segundos por operação
  • Verifique sua conexão com a internet e o status da API do GitHub

Erros de permissão negada

  • Certifique-se de que o GitHub CLI tem permissões adequadas para o repositório
  • Para repositórios de organizações, verifique se você tem acesso apropriado
  • Algumas operações exigem permissões de escrita (criar, editar, mesclar, fechar)

Dicas de Desempenho

  • Use nomes específicos de repositório e proprietário para respostas mais rápidas
  • Limite os resultados de pesquisa com parâmetros de limite apropriados
  • O servidor usa virtual threads para desempenho concorrente ideal
  • O GitHub CLI lida com limitação de taxa automaticamente

Obtendo Ajuda

  • Consulte a documentação do GitHub CLI: gh help
  • Revise o protocolo MCP: https://modelcontextprotocol.io/
  • Para problemas do servidor, ative o registro de depuração no application.properties

Considerações de Implantação

Versionamento do JAR

O processo de construção gera arquivos JAR com números de versão no nome (por exemplo, gh_mcp_server-1.0.0.jar). Ao implantar ou atualizar:

  1. Implantação Inicial: Use a versão atual na sua configuração do Claude Desktop:

    "args": ["-jar", "/path/to/gh_mcp_server/build/libs/gh_mcp_server-1.0.0.jar"]

  2. Atualizações de Versão: Ao atualizar para uma nova versão, você deve:

    • Construir a nova versão: ./gradlew build
    • Atualizar sua configuração do Claude Desktop com o novo nome do arquivo JAR
    • Reiniciar o Claude Desktop para carregar a nova versão

  3. Implantação Independente de Versão: Para implantação mais fácil, você pode:

    • Usar o symlink gerado automaticamente gh_mcp_server.jar (criado automaticamente durante a construção)
    • Usar a opção Gradle (usa automaticamente a versão mais recente)
    • Usar um script de implantação que lida com atualizações de versão

    Gerenciamento Automático de Symlink: O processo de construção cria e mantém automaticamente o symlink:

    • ./gradlew build cria gh_mcp_server.jar → gh_mcp_server-X.Y.Z.jar
    • ./gradlew clean build recria o symlink com a versão correta
    • Nenhum gerenciamento manual de symlink necessário

Gerenciamento de Configuração

  • Mantenha sua configuração do Claude Desktop em controle de versão
  • Documente a versão específica do JAR usada em produção
  • Considere usar variáveis de ambiente para caminhos em scripts de implantação

Stack de Tecnologia

  • Spring Boot 3.5.0 - Framework de aplicação
  • Spring AI 1.0.0 - Integração de IA e capacidades do servidor MCP
  • Java 21 - Linguagem de programação com suporte a virtual threads
  • GitHub CLI - Integração com a API do GitHub
  • Gradle - Ferramenta de construção
  • Spotless - Formatação de código com Google Java Format

Principais Recursos de Implementação

  • Virtual Threads (Java 21) - Operações de I/O concorrentes eficientes
  • ProcessBuilder - Execução segura de comandos com suporte a tempo limite
  • Records (Java 17) - Estruturas de dados imutáveis para resultados de comandos
  • Pattern Matching - Sintaxe moderna de Java para verificação de tipos
  • String Templates - Usando String.formatted() para construção mais limpa de strings

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.