Github MCP Server Java

Um servidor MCP pronto para produção que conecta qualquer agente de IA compatível com MCP à API do GitHub. Gerencie repositórios, issues, pull requests e buscas — tudo por meio de linguagem natural.

GitHubExperimente este MCPPatrocinado

Documentação

GitHub MCP Server — Java / Spring AI

Transporte: HTTP/SSE na porta 8080, compatível com Cursor e Claude Desktop de fábrica.

Por que este servidor?

Capacidade	Este servidor	API REST do GitHub
Gerenciamento de repositórios	✅	✅
Operações de issues e PRs	✅	✅
Controle de branches e commits	✅	✅
Busca de código e usuários	✅	✅
Interface em linguagem natural	✅	❌
Protocolo MCP (SSE)	✅	❌
Java / Spring AI	✅	❌
Suporte ao GitHub Enterprise	✅	✅

Ferramentas (38 no total)

Categoria	Quantidade	Ferramentas
Repositório	11	`create_repository`, `fork_repository`, `get_repository`, `list_commits`, `get_commit`, `get_file_contents`, `create_or_update_file`, `delete_file`, `create_branch`, `list_branches`, `merge_branch`
Issues	11	`create_issue`, `update_issue`, `add_issue_comment`, `list_issues`, `get_issue`, `close_issue`, `reopen_issue`, `assign_issue`, `unassign_issue`, `add_issue_labels`, `remove_issue_label`
Pull Requests	10	`create_pull_request`, `update_pull_request`, `list_pull_requests`, `get_pull_request`, `merge_pull_request`, `close_pull_request`, `reopen_pull_request`, `add_pull_request_comment`, `create_pull_request_review`, `submit_pull_request_review`
Busca	4	`search_code`, `search_issues`, `search_repositories`, `search_users`
Usuários	3	`get_authenticated_user`, `get_user`, `list_user_repositories`

Início rápido

# 1. Build
mvn clean package

# 2. Set credentials
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_...

# 3. Run (SSE transport — port 8080)
java -jar target/github-mcp-server-1.0.0.jar

# 4. Verify
curl http://localhost:8080/health

# 5. Inspect all tools
npx @modelcontextprotocol/inspector http://localhost:8080/sse

Obtenha seu token em Configurações do GitHub → Configurações de desenvolvedor → Tokens de acesso pessoal. Para GitHub Enterprise, defina GITHUB_HOST para a URL da sua instância.

Arquitetura

MCP Client (Cursor / Claude Desktop / other)
    │   HTTP/SSE transport (/sse + /mcp/message)
    ▼
Tool class  (@McpTool — thin delegation layer, validates required params)
    ▼
Service interface + impl  (business logic, error mapping, pagination)
    ▼
GitHubRestClient  (typed HTTP gateway, PAT auth, exception handling)
    ▼
GitHub REST API

A arquitetura é estritamente em camadas:

client/ — limite de integração com o GitHub (HTTP, Bearer-Auth, tratamento de erros)
service/ — lógica de domínio (filtragem, mapeamento, paginação)
tools/ — superfície voltada para MCP (descrições, validação de parâmetros, delegação)
Spring Boot — apenas wrapper de runtime e transporte

Cada ferramenta retorna um envelope consistente ApiResponse<T>:

{ "success": true,  "data": { ... } }
{ "success": false, "errorCode": "REPO_NOT_FOUND", "errorMessage": "..." }

Configuração

Propriedade	Variável de ambiente	Obrigatório	Padrão	Descrição
—	`GITHUB_PERSONAL_ACCESS_TOKEN`	✅	—	Token de acesso pessoal do GitHub
—	`GITHUB_HOST`	❌	`github.com`	Nome do host do GitHub (para GitHub Enterprise)
—	`GITHUB_READ_ONLY`	❌	`false`	Restringir a operações somente leitura
—	`GITHUB_TOOLSETS`	❌	all	Lista separada por vírgulas de conjuntos de ferramentas a habilitar
—	`GITHUB_TOOLS`	❌	all	Lista separada por vírgulas de ferramentas específicas a habilitar
—	`GITHUB_EXCLUDE_TOOLS`	❌	none	Lista separada por vírgulas de ferramentas a excluir

Criando um token de acesso pessoal do GitHub

Vá para Configurações do GitHub → Configurações de desenvolvedor → Tokens de acesso pessoal
Clique em "Gerar novo token (clássico)"
Selecione os seguintes escopos:
- repo — Controle total de repositórios privados
- workflow — Atualizar workflows do GitHub Actions
- read:org — Ler associação a organizações e equipes
- gist — Criar gists
- notifications — Acessar notificações
- read:user — Ler dados do perfil do usuário
Gere e copie o token

Configuração do cliente

Cursor (`.cursor/mcp.json`)

{
  "mcpServers": {
    "github": {
      "url": "http://localhost:8080/sse"
    }
  }
}

Claude Desktop (`claude_desktop_config.json`)

{
  "mcpServers": {
    "github": {
      "url": "http://localhost:8080/sse"
    }
  }
}

No macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

VS Code / GitHub Copilot

Modo URL (se o seu cliente suportar):

{
  "github.copilot.chat.mcp.servers": {
    "github": {
      "url": "http://localhost:8080/sse"
    }
  }
}

Modo comando (clientes somente stdio):

{
  "github.copilot.chat.mcp.servers": {
    "github": {
      "command": "java",
      "args": ["-jar", "/path/to/github-mcp-server-1.0.0.jar"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  }
}

Docker

# Build image
docker build -t github-mcp-server:latest .

# Run
docker run --rm -p 8080:8080 \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_... \
  github-mcp-server:latest

Se o GitHub Enterprise for executado em Docker no mesmo host, use host.docker.internal:

-e GITHUB_HOST=http://host.docker.internal:3000

Executando testes

mvn test

Estrutura de pacotes

com.github.mcp
├── GithubMcpApplication.java              @SpringBootApplication
├── config/
│   ├── GitHubProperties.java              @ConfigurationProperties — token, host, readOnly, toolsets
│   └── WebConfig.java                     Web configuration
├── client/
│   ├── GitHubRestClient.java              GET/POST/PATCH/DELETE HTTP gateway; typed exceptions
│   └── GitHubGraphqlClient.java           GraphQL client
├── controller/
│   └── HealthController.java              Health check endpoint (GET /health)
├── exception/
│   ├── GitHubMcpException.java            Base exception
│   └── GlobalExceptionHandler.java        Global error handler
├── dto/
│   ├── common/   ApiResponse · PagedResponse
│   ├── request/  *Request DTOs
│   └── response/ *Response DTOs
├── service/      Interfaces + impl — business logic, error mapping, pagination
└── tools/
    ├── RepositoryTools.java   (11 tools)
    ├── IssueTools.java        (11 tools)
    ├── PullRequestTools.java  (10 tools)
    ├── SearchTools.java       (4 tools)
    └── UserTools.java         (3 tools)

Solução de problemas

`401 Unauthorized`

Problema com o token. Verifique:

GITHUB_PERSONAL_ACCESS_TOKEN está definido corretamente
O token não expirou
O token tem os escopos necessários (veja Configuração)
Para GitHub Enterprise: confirme que GITHUB_HOST está definido para a URL da sua instância

`REPO_NOT_FOUND` / `404 Not Found`

O repositório pode ser privado e o token não possui o escopo repo, ou o proprietário/nome está incorreto.

Timeouts de conexão

O servidor se conecta a api.github.com (ou ao seu GITHUB_HOST). Garanta que o processo JVM tenha acesso de rede de saída.

Copilot / Claude não conseguem ver o servidor

Confirme que o servidor está em execução: curl http://localhost:8080/health
Confirme que o endpoint MCP SSE está ativo: curl http://localhost:8080/sse
Verifique se a URL na configuração do cliente aponta para http://localhost:8080/sse

Agradecimentos

Este projeto é uma adaptação em Java / Spring AI do GitHub MCP Server oficial, escrito em Go.

Licença

Licença MIT — veja LICENSE para detalhes.