GitHub

Gerencie repositórios do GitHub usando um token de acesso pessoal via CLI ou variáveis de ambiente.

Documentação

Servidor MCP do GitHub (Versão do Kosta)

Um servidor Model Context Protocol (MCP) que fornece operações abrangentes de repositórios GitHub — leitura e escrita — por meio de uma interface CLI simples. Criado para o Claude Desktop e outros clientes MCP.

v3.1.0 — Combina a expansão de ferramentas de escrita da v3 com transporte HTTP Streamable (/mcp), estrutura de migração OAuth, carregamento preguiçoso de ferramentas e opções de saída estruturada de ferramentas.

Recursos

Exploração de repositórios, leitura de arquivos e busca de código
Ciclo de vida completo de issues/PRs (listar, visualizar, criar, atualizar, mesclar, revisores, labels)
Histórico de commits, diffs e comparação de branches
Criação/atualização/exclusão de arquivos via commits diretos
Criação e exclusão de branches
Releases, criação/fork de repositórios e informações de usuário
Anotações de ferramentas (dicas de somente leitura, destrutivas) para seleção inteligente de ferramentas por IA
Instruções do servidor para orientação de fluxo de trabalho de IA
Limitação de taxa e tratamento abrangente de erros

Instalação e Uso

Início Rápido (Recomendado)

# Run directly with npx (no installation needed)
GITHUB_TOKEN=your_token_here npx github-mcp-server-kosta

# Idle auto-exit defaults to 5 minutes (prevents leaked stdio servers from piling up).
# Disable if you need an always-on process:
MCP_IDLE_TIMEOUT_MS=0 GITHUB_TOKEN=your_token_here npx github-mcp-server-kosta

# Not recommended (token is visible via `ps` on the machine):
npx github-mcp-server-kosta --github-token YOUR_GITHUB_TOKEN

# Streamable HTTP mode (native /mcp endpoint)
GITHUB_TOKEN=your_token_here npx github-mcp-server-kosta --transport http --http-port 3000

Instalação Global

npm install -g github-mcp-server-kosta
GITHUB_TOKEN=your_token_here github-mcp-server-kosta

Configuração do Token do GitHub

Acesse Configurações do GitHub → Configurações de desenvolvedor → Tokens de acesso pessoal
Gere um novo token (clássico) com estes escopos:
- repo (acesso total para repositórios privados + operações de escrita)
- public_repo (para repositórios públicos, somente leitura)
- read:user (para informações de usuário)
Use o token com a CLI:

npx github-mcp-server-kosta --github-token ghp_your_token_here

Ferramentas Disponíveis

Operações de Repositório

Ferramenta	Descrição
`github_repo_info`	Obter metadados do repositório (estrelas, forks, linguagem, etc.)
`github_list_contents`	Listar arquivos/diretórios em um caminho
`github_get_file_content`	Ler o conteúdo de um arquivo (retorna SHA para atualizações)
`github_get_readme`	Buscar e decodificar o README
`github_search_code`	Buscar código dentro de um repositório
`github_list_repos`	Listar repositórios de um usuário/organização
`github_search_repos`	Buscar repositórios globalmente
`github_create_repo`	Criar um novo repositório
`github_fork_repo`	Criar fork de um repositório existente

Issues e Pull Requests

Ferramenta	Descrição
`github_list_issues`	Listar issues (filtrar por estado, labels, responsável)
`github_get_issue`	Obter detalhes completos da issue
`github_list_pulls`	Listar PRs (filtrar por estado, head, branch base)
`github_get_pull`	Obter detalhes completos do PR com estatísticas de diff
`github_create_issue`	Criar uma nova issue
`github_update_issue`	Atualizar uma issue (ou PR) via API de Issues (título/corpo/estado/labels/responsáveis/milestone)
`github_create_issue_comment`	Comentar em uma issue ou PR
`github_create_pull_request`	Criar um pull request
`github_update_pull_request`	Atualizar um pull request
`github_merge_pull_request`	Mesclar um pull request
`github_request_reviewers`	Solicitar revisores para um pull request
`github_search_issues`	Buscar issues e pull requests (sintaxe de busca do GitHub)

Branches, Commits e Histórico

Ferramenta	Descrição
`github_list_branches`	Listar todos os branches
`github_list_commits`	Listar commits (filtrar por caminho, autor, data)
`github_get_commit`	Obter detalhes do commit com diff completo
`github_compare`	Comparar dois branches/tags/commits
`github_create_branch`	Criar um novo branch a partir de uma ref
`github_delete_branch`	Excluir um branch

Releases e Usuários

Ferramenta	Descrição
`github_list_releases`	Listar releases com notas e assets
`github_create_release`	Criar um release
`github_user_info`	Obter informações de perfil de usuário/org

Operações de Arquivo

Ferramenta	Descrição
`github_create_or_update_file`	Criar ou atualizar um arquivo via commit
`github_delete_file`	Excluir um arquivo via commit (requer SHA)

Labels

Ferramenta	Descrição
`github_list_labels`	Listar labels do repositório
`github_create_label`	Criar um label de repositório
`github_set_issue_labels`	Substituir todos os labels em uma issue/PR
`github_add_issue_labels`	Adicionar labels a uma issue/PR
`github_remove_issue_label`	Remover um label de uma issue/PR
`github_add_labels`	Alias de compatibilidade: adicionar labels a issue/PR
`github_remove_label`	Alias de compatibilidade: remover um único label

Carregamento Preguiçoso de Ferramentas (Opcional)

Ferramenta	Descrição
`github_tool_groups_list`	Listar grupos de ferramentas e se estão carregados
`github_tool_groups_load`	Carregar grupos de ferramentas e emitir `notifications/tools/list_changed`
`github_tool_catalog_search`	Buscar grupos/nomes de ferramentas sem carregar todas as ferramentas

Escape Hatch REST

Ferramenta	Descrição
`github_rest_get`	GET genérico contra a API REST do GitHub (baseado em caminho)
`github_rest_mutate`	Solicitação de escrita genérica (POST/PUT/PATCH/DELETE) protegida por `confirm: "CONFIRM_GITHUB_WRITE"`

Configuração do Cliente MCP

Para o Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["github-mcp-server-kosta", "--github-token", "YOUR_GITHUB_TOKEN"]
    }
  }
}

Opções da CLI

Options:
  -t, --github-token     GitHub access token for API requests (or set GITHUB_TOKEN / GITHUB_PERSONAL_ACCESS_TOKEN)
      --transport        Transport mode: stdio|http [default: stdio]
      --tool-mode        Tool listing mode: "full" or "lazy" [default: full]
      --preload-groups   Comma-separated tool group IDs to preload in lazy mode [default: core,search in lazy]
      --tool-schema-verbosity  Tool schema verbosity: "full" or "compact" [default: full]
      --tool-output      Tool output: text|structured|both [default: text]
      --tool-output-schema  Tool output schema: none|bootstrap|all_loose [default: none]
      --idle-timeout-ms  Exit after this many ms without receiving an MCP request (0 disables).
                         Defaults: stdio=0, http=300000 (unless MCP_IDLE_TIMEOUT_MS is set)
  -r, --rate-limit       Rate limit delay in ms between requests [default: 100]
      --http-host        HTTP bind host (http transport) [default: 127.0.0.1]
      --http-port        HTTP bind port (http transport; 0 chooses ephemeral) [default: 3000]
      --http-path        MCP endpoint path (http transport) [default: /mcp]
      --http-tls-key     TLS private key path (enables https when paired with --http-tls-cert)
      --http-tls-cert    TLS cert path (enables https when paired with --http-tls-key)
      --http-auth-token  Optional Bearer token required to access /mcp
      --http-allowed-origins  Comma-separated Origin allowlist (enforced only when Origin header is present)
      --http-allowed-hosts    Comma-separated Host allowlist (recommended when binding 0.0.0.0/::)
      --http-max-sessions     Maximum concurrent MCP sessions (DoS guard) [default: 50]
      --http-require-auth-on-public-bind  Refuse startup if binding non-localhost without --http-auth-token [default: false]
      --http-oauth-resource-metadata-url  Optional URL to advertise in WWW-Authenticate as resource_metadata
      --http-oauth-protected-resource-path  Optional local path to serve OAuth protected resource metadata JSON
      --http-oauth-authorization-server-issuer  Optional authorization server issuer included in metadata
      --http-oauth-scopes  Comma-separated scopes_supported included in metadata
      --http-oauth-cutover-path  Optional second MCP endpoint path for staged OAuth cutover (example: /mcp-oauth)
      --http-oauth-cutover-token  Bearer token required on cutover endpoint (falls back to --http-auth-token)
  -h, --help             Show help

Notas sobre Carregamento Preguiçoso de Ferramentas

Em --tool-mode lazy, o servidor expõe apenas ferramentas de inicialização mais quaisquer grupos pré-carregados (padrão: core,search).
Carregue grupos adicionais em tempo de execução usando github_tool_groups_load (por exemplo, issues, pulls, rest).
O servidor anuncia tools.listChanged: true e emite notifications/tools/list_changed após carregar grupos, mas alguns clientes MCP podem não atualizar automaticamente as listas de ferramentas. Se o seu cliente não atualizar, chame tools/list novamente (ou reinicie a sessão).

Notas sobre HTTP Streamable (`/mcp`)

--transport http expõe um único endpoint MCP (padrão http://127.0.0.1:3000/mcp) com suporte a GET, POST e DELETE.
Por padrão, o servidor vincula-se a 127.0.0.1 por segurança. Se você vincular a 0.0.0.0 ou outra interface, deve definir --http-auth-token e considerar fortemente --http-allowed-hosts e --http-allowed-origins.
No modo HTTP, o estado de carregamento preguiçoso de ferramentas é isolado por sessão: cada Mcp-Session-Id tem seu próprio estado de carregamento de grupos de ferramentas.
Proteção opcional de inicialização mais rigorosa: --http-require-auth-on-public-bind true recusa a inicialização ao vincular a não-localhost sem --http-auth-token.

supergateway + Baseline Cloudflare

Se você executar isso atrás do supergateway para conectores remotos do Claude.ai, fixe explicitamente os sinalizadores de transporte/sessão/protocolo do gateway:

supergateway \
  --stdio 'npx github-mcp-server-kosta -t "$GITHUB_TOKEN"' \
  --outputTransport streamableHttp \
  --streamableHttpPath /mcp \
  --protocolVersion 2025-06-18 \
  --stateful true \
  --sessionTimeout 900000 \
  --healthEndpoint /healthz \
  --healthEndpoint /readyz \
  --logLevel info

Consulte a documentação operacional:

docs/ops/baseline-connector-smoke.md
docs/ops/claude-connector-hardening.md
docs/ops/incident-playbook.md

Scripts de teste:

scripts/smoke/remote-mcp-smoke.sh
scripts/smoke/edge-header-check.sh

Estrutura OAuth (Preparação da Fase 2)

Este servidor agora suporta estrutura opcional de descoberta/desafio OAuth para implantação em etapas:

--http-oauth-resource-metadata-url: quando solicitações não autenticadas são rejeitadas (401), WWW-Authenticate inclui:
- Bearer resource_metadata="..."
--http-oauth-protected-resource-path: serve um documento JSON local de Metadados de Recurso Protegido OAuth.
--http-oauth-authorization-server-issuer: adiciona authorization_servers ao JSON de metadados.
--http-oauth-scopes: adiciona scopes_supported ao JSON de metadados.
--http-oauth-cutover-path: adiciona um segundo endpoint em etapas (por exemplo, /mcp-oauth) para que você possa manter o comportamento de /mcp inalterado enquanto testa a migração de conectores que exigem autenticação.
--http-oauth-cutover-token: token exigido no endpoint de migração; se não definido, o servidor volta para --http-auth-token.

Exemplo:

npx github-mcp-server-kosta \
  --transport http \
  --http-host 127.0.0.1 \
  --http-port 3000 \
  --http-path /mcp \
  --http-auth-token "$MCP_BEARER_TOKEN" \
  --http-oauth-resource-metadata-url "https://connector.example.com/.well-known/oauth-protected-resource" \
  --http-oauth-protected-resource-path "/.well-known/oauth-protected-resource" \
  --http-oauth-authorization-server-issuer "https://auth.example.com" \
  --http-oauth-scopes "mcp.read,mcp.write"

Exemplo de migração em etapas (/mcp aberto, /mcp-oauth protegido):

npx github-mcp-server-kosta \
  --transport http \
  --http-host 127.0.0.1 \
  --http-port 3000 \
  --http-path /mcp \
  --http-oauth-cutover-path /mcp-oauth \
  --http-oauth-cutover-token "$MCP_CUTOVER_TOKEN"

Importante:

Isso é estrutura para implantação em fases, não uma implementação completa de servidor de autorização OAuth.
Em implantações de conectores Claude.ai em produção, o padrão recomendado ainda é OAuth de propriedade do edge/gateway.

Orientação de Segurança em Linguagem Simples

Se você executar isso apenas na sua própria máquina e nada mais puder acessá-la, geralmente pode pular a autenticação.

Se você vincular o servidor HTTP a uma interface de rede que outros dispositivos possam acessar (por exemplo, --http-host 0.0.0.0), qualquer pessoa que possa acessar esse endereço poderá potencialmente usar seu token do GitHub por meio dessas ferramentas. Nesse caso, você deve:

Preferir colocar a autenticação no seu gateway (supergateway / Cloudflare / seu conector) para que o próprio servidor MCP permaneça apenas em localhost.
Ou definir --http-auth-token para que o endpoint /mcp exija um token Bearer.

Formatos de Resposta

A maioria das ferramentas suporta dois níveis de detalhe:

summary (padrão) — campos-chave concisos, pré-visualizações de 5 itens para listas
detailed — resposta completa da API do GitHub

Anotações de Ferramentas

Todas as ferramentas incluem anotações MCP para ajudar clientes de IA a tomar decisões inteligentes:

readOnlyHint — seguro chamar sem efeitos colaterais
destructiveHint — pode modificar ou excluir dados (por exemplo, atualizações de arquivos)
idempotentHint — seguro tentar novamente com os mesmos argumentos
openWorldHint — interage com a API externa do GitHub

Instruções do Servidor

O servidor fornece orientação de fluxo de trabalho para modelos de IA, incluindo:

Relacionamentos entre ferramentas (por exemplo, "use github_get_file_content para obter SHA antes de github_create_or_update_file")
Informações de limitação de taxa
Requisitos de permissão de token
Recomendações de modo de resposta

Licença

Licença MIT

Autor

Kosta Milovanovic (ildunari)

Contribuindo

Faça um fork do repositório
Crie seu branch de recurso
Faça commit das suas alterações
Envie para o branch
Crie um Pull Request