GitHub
Interaja com as APIs do GitHub para automação e gerenciamento de repositórios.
Documentação
GitHub MCP Server
O GitHub MCP Server é um servidor Model Context Protocol (MCP) que fornece integração perfeita com as APIs do GitHub, permitindo recursos avançados de automação e interação para desenvolvedores e ferramentas.
Casos de Uso
- Automatizar fluxos de trabalho e processos do GitHub.
- Extrair e analisar dados de repositórios do GitHub.
- Criar ferramentas e aplicativos com tecnologia de IA que interagem com o ecossistema do GitHub.
Pré-requisitos
- Para executar o servidor em um contêiner, você precisará ter o Docker instalado.
- Depois que o Docker estiver instalado, você também precisará garantir que o Docker esteja em execução. A imagem é pública; se você receber erros ao fazer pull, pode ter um token expirado e precisará
docker logout ghcr.io. - Por fim, você precisará Criar um Token de Acesso Pessoal do GitHub. O servidor MCP pode usar muitas das APIs do GitHub, então habilite as permissões que você se sentir confortável em conceder às suas ferramentas de IA (para saber mais sobre tokens de acesso, consulte a documentação).
Instalação
Uso com VS Code
Para instalação rápida, use um dos botões de instalação com um clique no topo deste README. Depois de concluir esse fluxo, alterne o modo Agente (localizado ao lado do campo de texto do Copilot Chat) e o servidor será iniciado.
Para instalação manual, adicione o seguinte bloco JSON ao arquivo User Settings (JSON) no VS Code. Você pode fazer isso pressionando Ctrl + Shift + P e digitando Preferences: Open User Settings (JSON).
{
"mcp": {
"inputs": [
{
"type": "promptString",
"id": "github_token",
"description": "GitHub Personal Access Token",
"password": true
}
],
"servers": {
"github": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"GITHUB_PERSONAL_ACCESS_TOKEN",
"ghcr.io/github/github-mcp-server"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"
}
}
}
}
}
Opcionalmente, você pode adicionar um exemplo semelhante (ou seja, sem a chave mcp) a um arquivo chamado .vscode/mcp.json no seu workspace. Isso permitirá que você compartilhe a configuração com outras pessoas.
{
"inputs": [
{
"type": "promptString",
"id": "github_token",
"description": "GitHub Personal Access Token",
"password": true
}
],
"servers": {
"github": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"GITHUB_PERSONAL_ACCESS_TOKEN",
"ghcr.io/github/github-mcp-server"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"
}
}
}
}
Saiba mais sobre o uso das ferramentas do servidor MCP na documentação do modo agente do VS Code.
Uso com Claude Desktop
{
"mcpServers": {
"github": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"GITHUB_PERSONAL_ACCESS_TOKEN",
"ghcr.io/github/github-mcp-server"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
}
}
}
}
Compilar a partir do código-fonte
Se você não tiver o Docker, pode usar go build para compilar o binário no diretório cmd/github-mcp-server e usar o comando github-mcp-server stdio com a variável de ambiente GITHUB_PERSONAL_ACCESS_TOKEN definida com seu token. Para especificar o local de saída da compilação, use a flag -o. Você deve configurar seu servidor para usar o executável compilado como seu command. Por exemplo:
{
"mcp": {
"servers": {
"github": {
"command": "/path/to/github-mcp-server",
"args": ["stdio"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
}
}
}
}
}
Configuração de Ferramentas
O GitHub MCP Server suporta habilitar ou desabilitar grupos específicos de funcionalidades por meio da flag --toolsets. Isso permite que você controle quais recursos da API do GitHub estão disponíveis para suas ferramentas de IA. Habilitar apenas os conjuntos de ferramentas que você precisa pode ajudar o LLM na escolha de ferramentas e reduzir o tamanho do contexto.
Conjuntos de Ferramentas Disponíveis
Os seguintes conjuntos de ferramentas estão disponíveis (todos estão ativados por padrão):
| Toolset | Descrição |
|---|---|
repos | Ferramentas relacionadas a repositórios (operações de arquivos, branches, commits) |
issues | Ferramentas relacionadas a issues (criar, ler, atualizar, comentar) |
users | Qualquer coisa relacionada a usuários do GitHub |
pull_requests | Operações de pull request (criar, mesclar, revisar) |
code_security | Alertas de varredura de código e recursos de segurança |
experiments | Recursos experimentais (não considerados estáveis) |
Especificando Conjuntos de Ferramentas
Para especificar os conjuntos de ferramentas que você deseja disponibilizar ao LLM, você pode passar uma lista de permissões de duas maneiras:
-
Usando Argumento de Linha de Comando:
github-mcp-server --toolsets repos,issues,pull_requests,code_security -
Usando Variável de Ambiente:
GITHUB_TOOLSETS="repos,issues,pull_requests,code_security" ./github-mcp-server
A variável de ambiente GITHUB_TOOLSETS tem precedência sobre o argumento de linha de comando se ambos forem fornecidos.
Usando Conjuntos de Ferramentas com Docker
Ao usar o Docker, você pode passar os conjuntos de ferramentas como variáveis de ambiente:
docker run -i --rm \
-e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
-e GITHUB_TOOLSETS="repos,issues,pull_requests,code_security,experiments" \
ghcr.io/github/github-mcp-server
O Conjunto de Ferramentas "all"
O conjunto de ferramentas especial all pode ser fornecido para habilitar todos os conjuntos de ferramentas disponíveis, independentemente de qualquer outra configuração:
./github-mcp-server --toolsets all
Ou usando a variável de ambiente:
GITHUB_TOOLSETS="all" ./github-mcp-server
Descoberta Dinâmica de Ferramentas
Nota: Este recurso está atualmente em beta e pode não estar disponível em todos os ambientes. Teste e nos avise se encontrar algum problema.
Em vez de começar com todas as ferramentas habilitadas, você pode ativar a descoberta dinâmica de conjuntos de ferramentas. Os conjuntos de ferramentas dinâmicos permitem que o host MCP liste e habilite conjuntos de ferramentas em resposta a um prompt do usuário. Isso deve ajudar a evitar situações em que o modelo fica confuso com o grande número de ferramentas disponíveis.
Usando a Descoberta Dinâmica de Ferramentas
Ao usar o binário, você pode passar a flag --dynamic-toolsets.
./github-mcp-server --dynamic-toolsets
Ao usar o Docker, você pode passar os conjuntos de ferramentas como variáveis de ambiente:
docker run -i --rm \
-e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
-e GITHUB_DYNAMIC_TOOLSETS=1 \
ghcr.io/github/github-mcp-server
GitHub Enterprise Server
A flag --gh-host e a variável de ambiente GITHUB_HOST podem ser usadas para definir o nome do host do GitHub Enterprise Server. Prefixe o nome do host com o esquema de URI https://, caso contrário, ele assume o padrão http://, que o GitHub Enterprise Server não suporta.
"github": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"GITHUB_PERSONAL_ACCESS_TOKEN",
"-e",
"GITHUB_HOST",
"ghcr.io/github/github-mcp-server"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}",
"GITHUB_HOST": "https://<your GHES domain name>"
}
}
i18n / Substituindo Descrições
As descrições das ferramentas podem ser substituídas criando um arquivo github-mcp-server-config.json no mesmo diretório do binário.
O arquivo deve conter um objeto JSON com os nomes das ferramentas como chaves e as novas descrições como valores. Por exemplo:
{
"TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "an alternative description",
"TOOL_CREATE_BRANCH_DESCRIPTION": "Create a new branch in a GitHub repository"
}
Você pode criar uma exportação das traduções atuais executando o binário com a flag --export-translations.
Esta flag preservará quaisquer traduções/substituições que você tenha feito, adicionando novas traduções que foram adicionadas ao binário desde a última exportação.
./github-mcp-server --export-translations
cat github-mcp-server-config.json
Você também pode usar variáveis de ambiente para substituir as descrições. Os nomes das variáveis de ambiente são os mesmos das chaves no arquivo JSON, prefixados com GITHUB_MCP_ e em letras maiúsculas.
Por exemplo, para substituir a ferramenta TOOL_ADD_ISSUE_COMMENT_DESCRIPTION, você pode definir a seguinte variável de ambiente:
export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description"
Ferramentas
Usuários
- get_me - Obtém detalhes do usuário autenticado
- Nenhum parâmetro necessário
Issues
-
get_issue - Obtém o conteúdo de uma issue em um repositório
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)issue_number: Número da issue (number, obrigatório)
-
get_issue_comments - Obtém comentários de uma issue do GitHub
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)issue_number: Número da issue (number, obrigatório)
-
create_issue - Cria uma nova issue em um repositório do GitHub
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)title: Título da issue (string, obrigatório)body: Conteúdo do corpo da issue (string, opcional)assignees: Nomes de usuário para atribuir a esta issue (string[], opcional)labels: Rótulos para aplicar a esta issue (string[], opcional)
-
add_issue_comment - Adiciona um comentário a uma issue
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)issue_number: Número da issue (number, obrigatório)body: Texto do comentário (string, obrigatório)
-
list_issues - Lista e filtra issues do repositório
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)state: Filtrar por estado ('open', 'closed', 'all') (string, opcional)labels: Rótulos para filtrar (string[], opcional)sort: Ordenar por ('created', 'updated', 'comments') (string, opcional)direction: Direção da ordenação ('asc', 'desc') (string, opcional)since: Filtrar por data (timestamp ISO 8601) (string, opcional)page: Número da página (number, opcional)perPage: Resultados por página (number, opcional)
-
update_issue - Atualiza uma issue existente em um repositório do GitHub
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)issue_number: Número da issue a ser atualizada (number, obrigatório)title: Novo título (string, opcional)body: Nova descrição (string, opcional)state: Novo estado ('open' ou 'closed') (string, opcional)labels: Novos rótulos (string[], opcional)assignees: Novos responsáveis (string[], opcional)milestone: Novo número de milestone (number, opcional)
-
search_issues - Pesquisa issues e pull requests
query: Consulta de pesquisa (string, obrigatório)sort: Campo de ordenação (string, opcional)order: Ordem de classificação (string, opcional)page: Número da página (number, opcional)perPage: Resultados por página (number, opcional)
Pull Requests
-
get_pull_request - Obtém detalhes de um pull request específico
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)pullNumber: Número do pull request (number, obrigatório)
-
list_pull_requests - Lista e filtra pull requests do repositório
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)state: Estado do PR (string, opcional)sort: Campo de ordenação (string, opcional)direction: Direção da ordenação (string, opcional)perPage: Resultados por página (number, opcional)page: Número da página (number, opcional)
-
merge_pull_request - Mescla um pull request
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)pullNumber: Número do pull request (number, obrigatório)commit_title: Título para o commit de mesclagem (string, opcional)commit_message: Mensagem para o commit de mesclagem (string, opcional)merge_method: Método de mesclagem (string, opcional)
-
get_pull_request_files - Obtém a lista de arquivos alterados em um pull request
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)pullNumber: Número do pull request (number, obrigatório)
-
get_pull_request_status - Obtém o status combinado de todas as verificações de status de um pull request
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)pullNumber: Número do pull request (number, obrigatório)
-
update_pull_request_branch - Atualiza o branch de um pull request com as alterações mais recentes do branch base
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)pullNumber: Número do pull request (number, obrigatório)expectedHeadSha: O SHA esperado da referência HEAD do pull request (string, opcional)
-
get_pull_request_comments - Obtém os comentários de revisão em um pull request
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)pullNumber: Número do pull request (number, obrigatório)
-
get_pull_request_reviews - Obtém as revisões de um pull request
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)pullNumber: Número do pull request (number, obrigatório)
-
create_pull_request_review - Cria uma revisão em um pull request
-
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)pullNumber: Número do pull request (number, obrigatório)body: Texto do comentário de revisão (string, opcional)event: Ação de revisão ('APPROVE', 'REQUEST_CHANGES', 'COMMENT') (string, obrigatório)commitId: SHA do commit a revisar (string, opcional)comments: Matriz de objetos de comentários específicos de linha para colocar comentários nas alterações do pull request (array, opcional)- Para comentários inline: forneça
path,position(ouline) ebody - Para comentários de várias linhas: forneça
path,start_line,line, opcionalmenteside/start_sideebody
- Para comentários inline: forneça
-
create_pull_request - Criar um novo pull request
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)title: Título do PR (string, obrigatório)body: Descrição do PR (string, opcional)head: Branch contendo as alterações (string, obrigatório)base: Branch para mesclar (string, obrigatório)draft: Criar como PR de rascunho (boolean, opcional)maintainer_can_modify: Permitir edições do mantenedor (boolean, opcional)
-
add_pull_request_review_comment - Adicionar um comentário de revisão a um pull request ou responder a um comentário existente
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)pull_number: Número do pull request (number, obrigatório)body: O texto do comentário de revisão (string, obrigatório)commit_id: O SHA do commit para comentar (string, obrigatório, a menos que use in_reply_to)path: O caminho relativo ao arquivo que exige um comentário (string, obrigatório, a menos que use in_reply_to)line: A linha do blob no diff do pull request à qual o comentário se aplica (number, opcional)side: O lado do diff para comentar (LEFT ou RIGHT) (string, opcional)start_line: Para comentários de várias linhas, a primeira linha do intervalo (number, opcional)start_side: Para comentários de várias linhas, o lado inicial do diff (LEFT ou RIGHT) (string, opcional)subject_type: O nível em que o comentário é direcionado (linha ou arquivo) (string, opcional)in_reply_to: O ID do comentário de revisão para responder (number, opcional). Quando especificado, apenas o corpo é obrigatório e os outros parâmetros são ignorados.
-
update_pull_request - Atualizar um pull request existente em um repositório do GitHub
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)pullNumber: Número do pull request a atualizar (number, obrigatório)title: Novo título (string, opcional)body: Nova descrição (string, opcional)state: Novo estado ('aberto' ou 'fechado') (string, opcional)base: Novo nome do branch base (string, opcional)maintainer_can_modify: Permitir edições do mantenedor (boolean, opcional)
Repositórios
-
create_or_update_file - Criar ou atualizar um único arquivo em um repositório
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)path: Caminho do arquivo (string, obrigatório)message: Mensagem do commit (string, obrigatório)content: Conteúdo do arquivo (string, obrigatório)branch: Nome do branch (string, opcional)sha: SHA do arquivo se estiver atualizando (string, opcional)
-
list_branches - Listar branches em um repositório do GitHub
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)page: Número da página (number, opcional)perPage: Resultados por página (number, opcional)
-
push_files - Enviar vários arquivos em um único commit
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)branch: Branch para enviar (string, obrigatório)files: Arquivos para enviar, cada um com caminho e conteúdo (array, obrigatório)message: Mensagem do commit (string, obrigatório)
-
search_repositories - Pesquisar repositórios do GitHub
query: Consulta de pesquisa (string, obrigatório)sort: Campo de ordenação (string, opcional)order: Ordem de ordenação (string, opcional)page: Número da página (number, opcional)perPage: Resultados por página (number, opcional)
-
create_repository - Criar um novo repositório do GitHub
name: Nome do repositório (string, obrigatório)description: Descrição do repositório (string, opcional)private: Se o repositório é privado (boolean, opcional)autoInit: Inicializar automaticamente com README (boolean, opcional)
-
get_file_contents - Obter o conteúdo de um arquivo ou diretório
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)path: Caminho do arquivo (string, obrigatório)ref: Referência do Git (string, opcional)
-
fork_repository - Fazer fork de um repositório
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)organization: Nome da organização de destino (string, opcional)
-
create_branch - Criar um novo branch
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)branch: Nome do novo branch (string, obrigatório)sha: SHA a partir do qual criar o branch (string, obrigatório)
-
list_commits - Obter uma lista de commits de um branch em um repositório
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)sha: Nome do branch, tag ou SHA do commit (string, opcional)path: Apenas commits que contenham este caminho de arquivo (string, opcional)page: Número da página (number, opcional)perPage: Resultados por página (number, opcional)
-
get_commit - Obter detalhes de um commit de um repositório
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)sha: SHA do commit, nome do branch ou nome da tag (string, obrigatório)page: Número da página, para arquivos no commit (number, opcional)perPage: Resultados por página, para arquivos no commit (number, opcional)
-
search_code - Pesquisar código em repositórios do GitHub
query: Consulta de pesquisa (string, obrigatório)sort: Campo de ordenação (string, opcional)order: Ordem de ordenação (string, opcional)page: Número da página (number, opcional)perPage: Resultados por página (number, opcional)
Usuários
- search_users - Pesquisar usuários do GitHub
q: Consulta de pesquisa (string, obrigatório)sort: Campo de ordenação (string, opcional)order: Ordem de ordenação (string, opcional)page: Número da página (number, opcional)perPage: Resultados por página (number, opcional)
Varredura de Código
-
get_code_scanning_alert - Obter um alerta de varredura de código
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)alertNumber: Número do alerta (number, obrigatório)
-
list_code_scanning_alerts - Listar alertas de varredura de código para um repositório
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)ref: Referência do Git (string, opcional)state: Estado do alerta (string, opcional)severity: Severidade do alerta (string, opcional)tool_name: O nome da ferramenta usada para varredura de código (string, opcional)
Varredura de Segredos
-
get_secret_scanning_alert - Obter um alerta de varredura de segredos
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)alertNumber: Número do alerta (number, obrigatório)
-
list_secret_scanning_alerts - Listar alertas de varredura de segredos para um repositório
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)state: Estado do alerta (string, opcional)secret_type: Os tipos de segredo a serem filtrados em uma lista separada por vírgulas (string, opcional)resolution: O status de resolução (string, opcional)
Recursos
Conteúdo do Repositório
-
Obter Conteúdo do Repositório Recupera o conteúdo de um repositório em um caminho específico.
- Modelo:
repo://{owner}/{repo}/contents{/path*} - Parâmetros:
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)path: Caminho do arquivo ou diretório (string, opcional)
- Modelo:
-
Obter Conteúdo do Repositório para um Branch Específico Recupera o conteúdo de um repositório em um caminho específico para um determinado branch.
- Modelo:
repo://{owner}/{repo}/refs/heads/{branch}/contents{/path*} - Parâmetros:
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)branch: Nome do branch (string, obrigatório)path: Caminho do arquivo ou diretório (string, opcional)
- Modelo:
-
Obter Conteúdo do Repositório para um Commit Específico Recupera o conteúdo de um repositório em um caminho específico para um determinado commit.
- Modelo:
repo://{owner}/{repo}/sha/{sha}/contents{/path*} - Parâmetros:
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)sha: SHA do commit (string, obrigatório)path: Caminho do arquivo ou diretório (string, opcional)
- Modelo:
-
Obter Conteúdo do Repositório para uma Tag Específica Recupera o conteúdo de um repositório em um caminho específico para uma determinada tag.
- Modelo:
repo://{owner}/{repo}/refs/tags/{tag}/contents{/path*} - Parâmetros:
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)tag: Nome da tag (string, obrigatório)path: Caminho do arquivo ou diretório (string, opcional)
- Modelo:
-
Obter Conteúdo do Repositório para um Pull Request Específico Recupera o conteúdo de um repositório em um caminho específico para um determinado pull request.
- Modelo:
repo://{owner}/{repo}/refs/pull/{prNumber}/head/contents{/path*} - Parâmetros:
owner: Proprietário do repositório (string, obrigatório)repo: Nome do repositório (string, obrigatório)prNumber: Número do pull request (string, obrigatório)path: Caminho do arquivo ou diretório (string, opcional)
- Modelo:
Uso da Biblioteca
A API Go exportada deste módulo deve atualmente ser considerada instável e sujeita a mudanças que quebram a compatibilidade. No futuro, podemos oferecer estabilidade; por favor, abra uma issue se houver um caso de uso em que isso seja valioso.
Licença
Este projeto é licenciado sob os termos da licença de código aberto MIT. Consulte MIT para os termos completos.