Git

by cyanheads

40 stars
926 downloads
Not rated
GitHub Website

About

Integrates with Git repositories using simple-git to enable core version control operations like cloning, committing, and branch management.

Details

Author
cyanheads
Repository
cyanheads/git-mcp-server
GitHub stars
40
Downloads
926
License
Apache License 2.0
Categories
Developer Tools, Other, Productivity, Design, Workplace, AI, Project Management, Infrastructure, Communication, Automation

Jump to

Built on mcp-ts-template.

| Feature | Details |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Declarative tools | Define capabilities in single, self-contained files. The framework handles registration, validation, and execution. |
| Error handling | Unified McpError system for consistent, structured error responses. |
| Authentication | Supports none, jwt, and oauth modes. |
| Pluggable storage | Swap backends (in-memory, filesystem, Supabase, Cloudflare KV/R2) without changing business logic. |
| Observability | Structured logging (Pino) and optional auto-instrumented OpenTelemetry for traces and metrics. |
| Dependency injection | Built with tsyringe for decoupled, testable architecture. |
| Cross-runtime | Auto-detects Bun or Node.js and uses the appropriate process spawning method. |
| Provider architecture | Pluggable git provider system. Current: CLI. Planned: isomorphic-git for edge deployment. |
| Working directory management | Session-specific directory context for multi-repo workflows. |
| Configurable git identity | Override author/committer info via environment variables, with fallback to global git config. |
| Commit signing | GPG/SSH signing (enabled by default) for commits, merges, rebases, cherry-picks, and tags. Silent fallback to unsigned on failure with signed/signingWarning fields in responses. |
| Safety | Destructive operations (git clean, git reset --hard) require explicit confirmation flags. |

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name Git
    Command (node, npx, python, etc.) npx
    Arguments
    • Argument 1 @cyanheads/git-mcp-server@latest
    Environment
    • LOGS_DIR ~/Developer/logs/git-mcp-server/
    • GIT_EMAIL casey@caseyjhand.com
    • GIT_BASE_DIR ~/Developer/
    • GIT_USERNAME cyanheads
    • MCP_LOG_LEVEL info
    • GIT_SIGN_COMMITS true
    • MCP_TRANSPORT_TYPE stdio

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

All configuration is validated at startup in src/config/index.ts. Key environment variables:

| Variable | Description | Default |
| :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ | :---------- |
| MCP_TRANSPORT_TYPE | Transport: stdio or http. | stdio |
| MCP_SESSION_MODE | HTTP session mode: stateless, stateful, or auto. | auto |
| MCP_RESPONSE_FORMAT | Response format: json (LLM-optimized), markdown (human-readable), or auto. | json |
| MCP_RESPONSE_VERBOSITY | Detail level: minimal, standard, or full. | standard |
| MCP_HTTP_PORT | HTTP server port. | 3015 |
| MCP_HTTP_HOST | HTTP server hostname. | 127.0.0.1 |
| MCP_HTTP_ENDPOINT_PATH | MCP request endpoint path. | /mcp |
| MCP_AUTH_MODE | Authentication mode: none, jwt, or oauth. | none |
| STORAGE_PROVIDER_TYPE | Storage backend: in-memory, filesystem, supabase, cloudflare-kv, r2. | in-memory |
| OTEL_ENABLED | Enable OpenTelemetry. | false |
| MCP_LOG_LEVEL | Minimum log level: debug, info, warn, error. | info |
| GIT_SIGN_COMMITS | GPG/SSH signing for commits, merges, rebases, cherry-picks, and tags. Falls back to unsigned on failure (see response signed/signingWarning). | true |
| GIT_AUTHOR_NAME | Git author name. Aliases: GIT_USERNAME, GIT_USER. Falls back to global git config. | (none) |
| GIT_AUTHOR_EMAIL | Git author email. Aliases: GIT_EMAIL, GIT_USER_EMAIL. Falls back to global git config. | (none) |
| GIT_BASE_DIR | Absolute path to restrict all git operations to a specific directory tree. | (none) |
| GIT_WRAPUP_INSTRUCTIONS_PATH | Path to custom markdown file with workflow instructions. | (none) |
| MCP_AUTH_SECRET_KEY | Required for jwt auth. 32+ character secret key. | (none) |
| OAUTH_ISSUER_URL | Required for oauth auth. OIDC provider URL. | (none) |

Add the following to your MCP client config (e.g., cline_mcp_settings.json). Update the environment variables to match your setup — especially the git identity fields.

{
  "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"
      }
    }
  }
}

Bun users: replace "command": "npx" with "command": "bunx".

For Streamable HTTP, set MCP_TRANSPORT_TYPE=http and MCP_HTTP_PORT=3015.

npx @cyanheads/git-mcp-server@latest

Configure through environment variables or your MCP client config.

git_init

Initialize a new Git repository.

git_clone

Clone a Git repository from a remote source.

git_status

Check the status of the working directory and staging area.

git_clean

Remove untracked files from the working directory.

git_add

Stage changes for the next commit.

git_commit

Create a new commit with staged changes.

git_diff

Show changes between commits, commit and working tree, etc.

git_log

View the commit history.

git_show

Show various types of objects (e.g., commits, trees).

git_blame

Show what revision and author last modified each line of a file.

git_reflog

Show reference logs.

git_changelog_analyze

Gather git context and instructions for LLM-driven changelog analysis.

git_branch

Manage branches in the repository.

git_checkout

Switch branches or restore working tree files.

git_merge

Merge changes from different branches.

git_rebase

Reapply commits on top of another base tip.

git_cherry_pick

Apply the changes introduced by some existing commits.

git_remote

Manage remote repository connections.

git_fetch

Download objects and refs from another repository.

git_pull

Fetch from a remote repo and merge.

git_push

Update remote refs along with associated objects.

git_tag

Create, list, delete, or verify tags.

git_stash

Stash the changes in a dirty working directory.

git_reset

Reset current HEAD to the specified state.

git_worktree

Manage multiple working trees.

git_set_working_dir

Set the current working directory.

git_clear_working_dir

Clear the current working directory.

git_wrapup_instructions

Provide instructions for wrapping up Git sessions.

28 git operations organized into seven categories:

| Category | Tools | Description |
| :------------------------ | :----------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ |
| Repository Management | git_init, git_clone, git_status, git_clean | Initialize repos, clone from remotes, check status, clean untracked files |
| Staging & Commits | git_add, git_commit, git_diff | Stage changes, create commits, compare changes |
| History & Inspection | git_log, git_show, git_blame, git_reflog | View commit history, inspect objects, trace authorship, view ref logs |
| Analysis | git_changelog_analyze | Gather git context and instructions for LLM-driven changelog analysis |
| Branching & Merging | git_branch, git_checkout, git_merge, git_rebase, git_cherry_pick | Manage branches, switch contexts, integrate changes, apply specific commits |
| Remote Operations | git_remote, git_fetch, git_pull, git_push | Configure remotes, fetch updates, synchronize repositories, publish changes |
| Advanced Workflows | git_tag, git_stash, git_reset, git_worktree, git_set_working_dir, git_clear_working_dir, git_wrapup_instructions | Tag releases (list/create/delete/verify), stash changes, reset state, manage worktrees, set/clear session directory |

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

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

Linux

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

Macos

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

Windows

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

Git Status: main

Staged (2)

- src/index.ts - README.md

Unstaged (1)

- package.json 

The LLM always receives the complete structured data via responseFormatter — full file lists, metadata, timestamps — regardless of what the client displays. Verbosity controls how much detail is included: minimal (core fields only), standard (balanced), or full (everything).

Development guide


See AGENTS.md for architecture, tool development patterns, and contribution rules.


Testing


Tests use Bun's test runner with Vitest compatibility.
sh
bun test # Run all tests
bun test --coverage # With coverage
bun run devcheck # Lint, format, typecheck, audit



Roadmap


The server uses a provider-based architecture for git operations:


- CLI provider (current) — Full 28-tool coverage via native git CLI. Requires local git installation.

- Isomorphic git provider (planned) — Pure JS implementation for edge deployment (Cloudflare Workers, Vercel Edge, Deno Deploy). Uses isomorphic-git.

- GitHub API provider (maybe) — Cloud-native operations via GitHub REST/GraphQL APIs, no local repo required.


Contributing


Issues and pull requests are welcome. Run checks before submitting:
sh
npm run devcheck
npm test
```

License

Apache 2.0. See LICENSE.

---

<div align="center">
<p>Built with the <a href="https://github.com/cyanheads/mcp-ts-template">mcp-ts-template</a></p>
<p>
<a href="https://github.com/sponsors/cyanheads">Sponsor this project</a> ·
<a href="https://www.buymeacoffee.com/cyanheads">Buy me a coffee</a>
</p>
</div>

No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Install

Add to Claude Desktop or Cursor

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

More like this

Similar MCP servers you might find useful

Browse category

Sequential Thinking

Sequential Thinking is an MCP server that provides a tool for dynamic and reflective problem-solving through a structured, step-by-step thinking process. It is…

88.2k
Other

Time

A Model Context Protocol server that provides time and timezone conversion capabilities. It enables LLMs to get current time information and perform timezone…

88.2k
Productivity

Filesystem

Filesystem is a Node.js server that implements the Model Context Protocol (MCP) for filesystem operations. It enables AI assistants to read, write, and manage…

88.1k
Other