Git Quick Stats Server

This folder contains a small MCP server that exposes git-quick-stats commands as MCP tools.

Setup

Install uv first (one-time):

curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

cd mcp-server
uv venv .venv
uv sync --dev

Or using Make:

make install

This installs:

• Runtime dependencies from pyproject.toml
• Development tools (including Black) from the dev dependency group

Run

uv run -m src.server

The server uses stdio transport, so configure your MCP client to launch this command.

On first tool execution, the server automatically downloads git-quick-stats into .mcp-tools/git-quick-stats inside this project if the script is not already present at project root.

To pin a specific upstream branch/tag/commit for downloads, set:

export GIT_QUICK_STATS_REF=<ref>

Example MCP Client Config

{
  "mcpServers": {
    "git-quick-stats": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/git-quick-stats/mcp-server",
        "-m",
        "src.server"
      ]
    }
  }
}

VS Code Config

Add one of the following entries to your VS Code MCP settings depending on your OS.

Windows (native Python/uv)

{
  "mcpServers": {
    "git-quick-stats": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:\\absolute\\path\\to\\git-quick-stats\\mcp-server",
        "-m",
        "src.server"
      ]
    }
  }
}

Windows (WSL Ubuntu)

{
  "mcpServers": {
    "git-quick-stats": {
      "command": "wsl.exe",
      "args": [
        "-d",
        "Ubuntu",
        "uv",
        "run",
        "--directory",
        "/home/your-user/projects/git-quick-stats/mcp-server",
        "-m",
        "src.server"
      ]
    }
  }
}

Linux

{
  "mcpServers": {
    "git-quick-stats": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/git-quick-stats/mcp-server",
        "-m",
        "src.server"
      ]
    }
  }
}

macOS

{
  "mcpServers": {
    "git-quick-stats": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/Users/your-user/path/to/git-quick-stats/mcp-server",
        "-m",
        "src.server"
      ]
    }
  }
}

Make Targets

make help
make bootstrap-uv
make install
make run
make format
make format-check

Docker Compose

Run the MCP server with Docker Compose:

docker compose up --build

Or via Make:

make docker-up
make docker-logs
make docker-down

Usage Notes

• Set repo_path to the git repository you want to inspect.
• Some options need extra values, which should be passed using tool arguments:
  • author for options that need _GIT_AUTHOR
  • branch for options that need _GIT_BRANCH
  • tag for options that need _GIT_TAG
• The --new-contributors option prompts for a date in the shell script. Use stdin_input with one date line, for example: 2025-01-01\n.

AI Output Example

Example tool call from an AI assistant:

{
  "tool": "run_git_quick_stats",
  "arguments": {
    "option": "--new-contributors",
    "repo_path": "/absolute/path/to/git-quick-stats",
    "stdin_input": "2025-01-01\n"
  }
}

Example tool result:

{
  "ok": true,
  "exit_code": 0,
  "stdout": "New contributors since 2025-01-01:\\n\\n     1  [email protected]\\n...",
  "stderr": ""
}

Example AI response to user:

New contributors report generated successfully using stdin date input (2025-01-01). I can also run the same report for another date range if you want.