---
since: 1.1.3
---

# gitaiflow MCP Server

> **v1.1.3** — MCP adapter for the existing `gitaiflow` AOT executable.

## What is gitaiflow MCP?

`gitaiflow MCP` is a thin MCP adapter around the existing `gitaiflow` executable.

It owns:

- MCP transport (`streamable-http` and `stdio`)
- MCP tool registration and schemas
- bearer-token authentication for Streamable HTTP
- request rate limiting
- workspace validation
- subprocess execution
- MCP response shaping
- changed-artifact detection

It does **not** reimplement gitaiflow's Git, diff, AI, caching, usage, changelog, release-note, or artifact-generation logic.

```mermaid
flowchart LR
    Client["MCP client"] --> Transport["Streamable HTTP / stdio"]
    Transport --> MCP["gitaiflow MCP adapter"]
    MCP --> Tools["6 MCP tools"]
    Tools --> Runner["_run()"]
    Runner --> Binary["gitaiflow AOT"]
    Binary --> Repo["Git repository"]
```

## Version

For this release:

```text
gitaiflow       1.1.3
MCP adapter     1.1.3
AOT binary      1.1.3
```

There is one gitaiflow binary distribution stream. Native MCP, Docker MCP, and the Claude Desktop integration use that same gitaiflow release.

## Installation: choose your path

There are two different audiences and two different installation paths.

### End user — Claude Desktop MCPB

If you only want to use gitaiflow MCP from Claude Desktop, use the packaged MCPB extension. You do **not** need a source checkout, Docker, Python, `.mcp.env`, or manual MCP server configuration.

macOS / Linux:

```bash
curl -fsSL https://install.djangoplay.org/gitaiflow-mcp | bash
```

Windows PowerShell:

```powershell
irm https://install.djangoplay.org/gitaiflow-mcp.ps1 | iex
```

The installer downloads the platform-specific `.mcpb` file to the default Downloads directory and prints its full path. Open the downloaded `.mcpb` file with Claude Desktop to install the extension.

After installation, the extension manages the MCP server and gitaiflow executable according to its normal binary-resolution rules. End users do not need the Docker instructions in this repository.

### Developer — local source/Docker verification

If you are developing or validating the MCP server itself, continue with:

**[MCP Documentation Index](./documentation-map.md)**

The developer path is:

```text
Getting Started
    ↓
Native MCP
    ↓
Docker MCP
    ↓
MCP Inspector
    ↓
Claude Desktop
    ↓
Release gate
```

## Documentation

The documentation index is the primary navigation point for both new and existing developers. It explains installation, configuration, verification, Docker, MCP Inspector, Claude Desktop, troubleshooting, and release preparation.

**[MCP Documentation Index](./documentation-map.md)**

## MCP tools

| Tool | Required | Optional |
|---|---|---|
| `gitaiflow_change_summary` | `remote` | `base_branch`, `path` |
| `gitaiflow_last_summary` | — | `path` |
| `gitaiflow_changelog` | `remote` | `since`, `until` |
| `gitaiflow_release_notes` | — | `path` |
| `gitaiflow_usage` | — | `scope`, `since`, `until` |
| `gitaiflow_list_models` | — | `free_only`, `as_json` |

The MCP layer passes the corresponding CLI arguments to gitaiflow. It does not invent repository-specific remote names.

## Configuration boundary

There are two configuration systems. Keep them separate.

### MCP configuration

MCP runtime settings belong in `.mcp.env`, the process environment, or the deployment environment.

Typical local settings:

```text
MCP_TRANSPORT=streamable-http
MCP_API_TOKEN=<local-secret>
MCP_WORKSPACE=/absolute/path/to/workspace
MCP_ALLOWED_WORKSPACES=/absolute/path/to/workspace
MCP_EXECUTION_TIMEOUT=120
MCP_RATE_LIMIT=100
MCP_RATE_WINDOW_SECONDS=60
```

`MCP_RATE_LIMIT=100` is a local development value used for repeated Inspector/manual requests. The application default is `5` requests per 60 seconds.

For a workspace containing multiple repositories, `MCP_WORKSPACE` and `MCP_ALLOWED_WORKSPACES` identify the workspace container, while the tool `path` selects the individual Git repository inside it. For example:

```text
Host:
/Users/<user>/projects/
├── gitaiflow/          ← Git repository
├── djangoplay-cli/     ← Git repository
└── issuetracker/       ← Git repository

Docker:
/workspace/
├── gitaiflow/
├── djangoplay-cli/
└── issuetracker/
```

The Docker environment is therefore:

```text
MCP_WORKSPACE=/workspace
MCP_ALLOWED_WORKSPACES=/workspace
```

A request for `path="gitaiflow"` resolves to `/workspace/gitaiflow` and that directory must itself be a Git repository root.

### gitaiflow configuration

The existing gitaiflow configuration remains the source of truth:

```text
~/.gitaiflow/config.env
```

for:

```text
AI_PROVIDER
AI_API_KEY
AI_BASE_URL
AI_MODEL
```

Do not put workspace paths or developer binary paths in `~/.gitaiflow/config.env`.

For Docker, mount:

```text
$HOME/.gitaiflow  →  /root/.gitaiflow
```

The mount must be writable because gitaiflow persists local state such as `usage.jsonl`.

### `.mcp.env` and Docker overrides

When Docker uses:

```bash
--env-file .mcp.env
```

and also supplies:

```bash
-e MCP_WORKSPACE=/workspace
-e MCP_ALLOWED_WORKSPACES=/workspace
```

the explicit `-e` values are the effective container values. This is intentional: `.mcp.env` can keep native host paths while Docker uses container paths.

Do not change the host paths in `.mcp.env` merely to make Docker work.

## Transports

### Streamable HTTP

Default transport:

```text
MCP_TRANSPORT=streamable-http
```

Endpoints:

```text
http://localhost:8080/mcp
http://localhost:8080/health
```

Use this transport for native local verification, Docker verification, MCP Inspector, and service-style deployments.

### stdio

```text
MCP_TRANSPORT=stdio
```

The server communicates through stdin/stdout and does not start Uvicorn.

This is the transport used by local desktop clients such as Claude Desktop.

## Docker model

For a multi-repository developer workspace, the important filesystem invariant is:

```text
Host parent workspace containing Git repositories
        ↓
        /workspace
```

For example:

```text
/Users/<user>/projects/
├── gitaiflow/.git
├── djangoplay-cli/.git
├── astwire/.git
└── issuetracker/.git
```

is mounted as:

```text
/workspace/
├── gitaiflow/.git
├── djangoplay-cli/.git
├── astwire/.git
└── issuetracker/.git
```

`/workspace` itself does **not** need to be a Git repository in this multi-repository layout. The selected repository, such as `/workspace/gitaiflow`, must be its own Git repository root.

Do not use `$PWD` blindly in Docker commands. If `$PWD` is `.../gitaiflow`, it mounts only that repository as `/workspace` and prevents repository-name selection across sibling repositories. Resolve the intended parent workspace explicitly.

For v1.1.3 local Docker verification, the tested AOT binary is explicitly mounted into the container:

```text
installers/AOT/v1.1.3/gitaiflow-linux-arm64
    →
/app/bin/gitaiflow
```

Use the matching Linux binary for the container architecture.

Do not assume that `/app/bin/gitaiflow` exists merely because the Docker image starts successfully.

## Where to go next

| Document | Purpose |
|---|---|
| [`MCP-GETTING-STARTED.md`](./getting-started.md) | End-user installation overview plus developer setup and configuration |
| [`MCP-LOCAL-VERIFICATION.md`](./local-verification.md) | Verification map and order of operations |
| [`MCP-DOCKER-VERIFICATION.md`](./docker-verification.md) | Multi-repository Docker build, mounts, AOT, HTTP, and stdio verification |
| [`MCP-INSPECTOR-VERIFICATION.md`](./inspector-verification.md) | MCP protocol/tool/schema verification |
| [`MCP-CLAUDE-DESKTOP.md`](./claude-desktop.md) | Claude Desktop stdio, Docker configuration, and MCPB integration |
| [`MCP-RUNBOOK.md`](../runbooks/mcp-troubleshooting.md) | Troubleshooting and diagnosis |
| [`MCP-RELEASE-CHECKLIST.md`](../runbooks/mcp-release-checklist.md) | v1.1.3 release gate |

Cloud Run is the next deployment evolution and is intentionally outside the v1.1.3 local verification gate.