Git MCP Server

---

Ferramentas

28 operações git organizadas em sete categorias:

Categoria	Ferramentas	Descrição
Gerenciamento de Repositório	git_init, git_clone, git_status, git_clean	Inicializar repositórios, clonar de remotos, verificar status, limpar arquivos não rastreados
Staging & Commits	git_add, git_commit, git_diff	Preparar alterações, criar commits, comparar alterações
Histórico & Inspeção	git_log, git_show, git_blame, git_reflog	Visualizar histórico de commits, inspecionar objetos, rastrear autoria, visualizar logs de referências
Análise	git_changelog_analyze	Coletar contexto git e instruções para análise de changelog orientada por LLM
Ramificação & Merge	git_branch, git_checkout, git_merge, git_rebase, git_cherry_pick	Gerenciar branches, alternar contextos, integrar alterações, aplicar commits específicos
Operações Remotas	git_remote, git_fetch, git_pull, git_push	Configurar remotos, buscar atualizações, sincronizar repositórios, publicar alterações
Fluxos de Trabalho Avançados	git_tag, git_stash, git_reset, git_worktree, git_set_working_dir, git_clear_working_dir, git_wrapup_instructions	Marcar versões (listar/criar/excluir/verificar), guardar alterações, redefinir estado, gerenciar worktrees, definir/limpar diretório de sessão

Recursos

Recurso	URI	Descrição
Diretório de Trabalho Git	git://working-directory	O diretório de trabalho da sessão atual, definido via git_set_working_dir.

Prompts

Prompt	Descrição	Parâmetros
Git Wrap-up	Protocolo de fluxo de trabalho para concluir sessões git: revisar, documentar, commitar e marcar alterações.	changelogPath, createTag.

Primeiros passos

Runtime

Funciona com Bun e Node.js. O runtime é detectado automaticamente.

Runtime	Comando	Versão Mínima
Node.js	npx @cyanheads/git-mcp-server@latest	>= 20.0.0
Bun	bunx @cyanheads/git-mcp-server@latest	>= 1.2.0

Configuração do cliente MCP

Adicione o seguinte à configuração do seu cliente MCP (ex.: cline_mcp_settings.json). Atualize as variáveis de ambiente para corresponder à sua configuração — especialmente os campos de identidade git.

{
  "mcpServers": {
    "git-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["@cyanheads/git-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "GIT_BASE_DIR": "~/Developer/",
        "LOGS_DIR": "~/Developer/logs/git-mcp-server/",
        "GIT_USERNAME": "cyanheads",
        "GIT_EMAIL": "casey@caseyjhand.com",
        "GIT_SIGN_COMMITS": "true"
      }
    }
  }
}

Usuários de Bun: substitua "command": "npx" por "command": "bunx".

Para Streamable HTTP, defina MCP_TRANSPORT_TYPE=http e MCP_HTTP_PORT=3015.

Recursos

Construído sobre mcp-ts-template.

Recurso	Detalhes
Ferramentas declarativas	Defina capacidades em arquivos únicos e autocontidos. O framework lida com registro, validação e execução.
Tratamento de erros	Sistema unificado McpError para respostas de erro consistentes e estruturadas.
Autenticação	Suporta modos none, jwt e oauth.
Armazenamento plugável	Troque backends (in-memory, filesystem, Supabase, Cloudflare KV/R2) sem alterar a lógica de negócio.
Observabilidade	Logging estruturado (Pino) e OpenTelemetry opcional com auto-instrumentação para traces e métricas.
Injeção de dependência	Construído com tsyringe para arquitetura desacoplada e testável.
Multi-runtime	Detecta automaticamente Bun ou Node.js e usa o método de spawn de processo apropriado.
Arquitetura de provedores	Sistema de provedores git plugável. Atual: CLI. Planejado: isomorphic-git para implantação em edge.
Gerenciamento de diretório de trabalho	Contexto de diretório específico da sessão para fluxos de trabalho multi-repositório.
Identidade git configurável	Substitua informações de autor/committer via variáveis de ambiente, com fallback para a configuração git global.
Assinatura de commits	Assinatura GPG/SSH (habilitada por padrão) para commits, merges, rebases, cherry-picks e tags. Fallback silencioso para não assinado em falha com campos signed/signingWarning nas respostas.
Segurança	Operações destrutivas (git clean, git reset --hard) exigem flags de confirmação explícitas.

Segurança

• Todos os caminhos de arquivo são validados e sanitizados para prevenir travessia de diretórios.
• GIT_BASE_DIR opcional restringe operações a uma árvore de diretórios específica para sandboxing multi-tenant.
• Comandos git usam argumentos validados via spawn de processo — sem interpolação de shell.
• Suporte a JWT e OAuth para implantações autenticadas.
• Rate limiting opcional via serviço RateLimiter gerenciado por DI.
• Todas as operações são registradas com contexto de requisição para auditoria.

Configuração

Toda a configuração é validada na inicialização em src/config/index.ts. Principais variáveis de ambiente:

Variável	Descrição	Padrão
MCP_TRANSPORT_TYPE	Transporte: stdio ou http.	stdio
MCP_SESSION_MODE	Modo de sessão HTTP: stateless, stateful ou auto.	auto
MCP_RESPONSE_FORMAT	Formato de resposta: json (otimizado para LLM), markdown (legível para humanos) ou auto.	json
MCP_RESPONSE_VERBOSITY	Nível de detalhe: minimal, standard ou full.	standard
MCP_HTTP_PORT	Porta do servidor HTTP.	3015
MCP_HTTP_HOST	Nome do host do servidor HTTP.	127.0.0.1
MCP_HTTP_ENDPOINT_PATH	Caminho do endpoint de solicitação MCP.	/mcp
MCP_AUTH_MODE	Modo de autenticação: none, jwt ou oauth.	none
STORAGE_PROVIDER_TYPE	Backend de armazenamento: in-memory, filesystem, supabase, cloudflare-kv, r2.	in-memory
OTEL_ENABLED	Ativar OpenTelemetry.	false
MCP_LOG_LEVEL	Nível mínimo de log: debug, info, warn, error.	info
GIT_SIGN_COMMITS	Assinatura GPG/SSH para commits, merges, rebases, cherry-picks e tags. Reverte para não assinado em caso de falha (veja resposta signed/signingWarning).	true
GIT_AUTHOR_NAME	Nome do autor Git. Aliases: GIT_USERNAME, GIT_USER. Reverte para a configuração global do git.	(none)
GIT_AUTHOR_EMAIL	E-mail do autor Git. Aliases: GIT_EMAIL, GIT_USER_EMAIL. Reverte para a configuração global do git.	(none)
GIT_BASE_DIR	Caminho absoluto para restringir todas as operações git a uma árvore de diretórios específica.	(none)
GIT_WRAPUP_INSTRUCTIONS_PATH	Caminho para arquivo markdown personalizado com instruções de fluxo de trabalho.	(none)
MCP_AUTH_SECRET_KEY	Necessário para autenticação jwt. Chave secreta com 32+ caracteres.	(none)
OAUTH_ISSUER_URL	Necessário para autenticação oauth. URL do provedor OIDC.	(none)

Executando o servidor

Via gerenciador de pacotes (sem instalação)

npx @cyanheads/git-mcp-server@latest

Configure por meio de variáveis de ambiente ou da configuração do seu cliente MCP.

Desenvolvimento local

# Build and run
npm run rebuild
npm run start:stdio   # or start:http

# Dev mode with hot reload
npm run dev:stdio     # or dev:http

# Checks and tests
npm run devcheck      # lint, format, typecheck
npm test

Cloudflare Workers

npm run build:worker   # Build the worker bundle
npm run deploy:dev     # Run locally with Wrangler
npm run deploy:prod    # Deploy to Cloudflare

Estrutura do projeto

Diretório	Finalidade
src/mcp-server/tools	Definições de ferramentas (*.tool.ts). As capacidades Git ficam aqui.
src/mcp-server/resources	Definições de recursos (*.resource.ts). Fontes de dados de contexto Git.
src/mcp-server/transports	Implementações de transporte HTTP e STDIO, incluindo autenticação.
src/storage	Abstração StorageService e implementações de provedores.
src/services	Provedor de serviços Git (operações git baseadas em CLI).
src/container	Registros e tokens do contêiner de injeção de dependência.
src/utils	Utilitários de logging, tratamento de erros, desempenho e segurança.
src/config	Análise e validação de variáveis de ambiente (Zod).
tests/	Testes unitários e de integração, espelhando a estrutura src/.

Formato de resposta

Configure o formato de saída e a verbosidade via MCP_RESPONSE_FORMAT e MCP_RESPONSE_VERBOSITY.

Formato JSON (padrão, otimizado para consumo por LLM):

{
  "success": true,
  "branch": "main",
  "staged": ["src/index.ts", "README.md"],
  "unstaged": ["package.json"],
  "untracked": []
}

Formato Markdown (legível para humanos):

# Git Status: main

## Staged (2)
- src/index.ts
- README.md

## Unstaged (1)
- package.json

O LLM sempre recebe os dados estruturados completos via responseFormatter — listas completas de arquivos, metadados, timestamps — independentemente do que o cliente exibe. A verbosidade controla quanto detalhe é incluído: minimal (apenas campos principais), standard (equilibrado) ou full (tudo).

Guia de desenvolvimento

Consulte AGENTS.md para arquitetura, padrões de desenvolvimento de ferramentas e regras de contribuição.

Testes

Os testes usam o executor de testes do Bun com compatibilidade com Vitest.

bun test              # Run all tests
bun test --coverage   # With coverage
bun run devcheck      # Lint, format, typecheck, audit

Roadmap

O servidor usa uma arquitetura baseada em provedores para operações git:

• Provedor CLI (atual) — Cobertura completa de 28 ferramentas via CLI nativa do git. Requer instalação local do git.
• Provedor git isomórfico (planejado) — Implementação pura em JS para implantação em edge (Cloudflare Workers, Vercel Edge, Deno Deploy). Usa isomorphic-git.
• Provedor GitHub API (talvez) — Operações nativas em nuvem via APIs REST/GraphQL do GitHub, sem repositório local necessário.

Contribuindo

Issues e pull requests são bem-vindos. Execute as verificações antes de enviar:

npm run devcheck
npm test

Licença

Apache 2.0. Consulte LICENSE.

---