gitaiflow MCP — Claude Desktop Integration · gitaiflow

If you are an end user, install the packaged MCPB extension instead of configuring Docker manually. See the installation section in MCP overview.

For developer verification, follow:

text

native MCP
    ↓
Docker MCP
    ↓
MCP Inspector
    ↓
Claude Desktop

1. What Claude Desktop adds

Claude introduces another process boundary:

flowchart TB
    Claude["Claude Desktop"]
    STDIO["stdio"]
    MCP["gitaiflow MCP"]
    AOT["gitaiflow AOT"]
    Repo["Selected Git repository"]

    Claude --> STDIO --> MCP --> AOT --> Repo

The goal is to prove that Claude can launch the server, initialize MCP, discover the tools, invoke a tool, and receive the result.

2. End-user installation

For normal Claude Desktop use, install the packaged MCPB extension.

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 .mcpb file with Claude Desktop to install the extension.

The end-user MCPB path does not require:

Docker
Python
.mcp.env
a source checkout
a manual docker run command

3. Docker stdio model for developers

Claude launches:

text

docker run

The container uses:

text

MCP_TRANSPORT=stdio

There is no HTTP port mapping.

For a multi-repository developer workspace, mount the parent directory containing the repositories:

text

/Users/<user>/pyc/missionmq/gl
        →
/workspace

For example:

text

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

Then:

text

MCP_WORKSPACE=/workspace
MCP_ALLOWED_WORKSPACES=/workspace

Claude can select repositories by name, for example path="gitaiflow".

The gitaiflow configuration is mounted as:

text

$HOME/.gitaiflow → /root/.gitaiflow

For the v1.1.3 local Docker test, the matching AOT binary is explicitly mounted:

text

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

4. Verify Docker stdio outside Claude first

Do this before editing Claude Desktop configuration.

Define the parent workspace explicitly:

bash

export MCP_HOST_WORKSPACE="/Users/<user>/pyc/missionmq/gl"

Then run:

bash

docker run --rm -i \
  --env-file .mcp.env \
  -e MCP_TRANSPORT=stdio \
  -e MCP_WORKSPACE=/workspace \
  -e MCP_ALLOWED_WORKSPACES=/workspace \
  -e GITAIFLOW_BINARY=/app/bin/gitaiflow \
  -v "$HOME/.gitaiflow:/root/.gitaiflow" \
  -v "$MCP_HOST_WORKSPACE:/workspace" \
  -v "$MCP_HOST_WORKSPACE/gitaiflow/installers/AOT/v1.1.3/gitaiflow-linux-arm64:/app/bin/gitaiflow:ro" \
  gitaiflow-mcp:local

Expected:

text

stdio starts
no Uvicorn
no HTTP listener

If this does not work, do not move to Claude.

Verify the actual Docker filesystem before Claude

Start the HTTP variant when you need an inspectable running container, then verify:

bash

docker ps --filter name=gitaiflow-mcp

bash

docker exec gitaiflow-mcp sh -c '
echo "=== WORKSPACE ==="
ls -lad /workspace

echo
echo "=== GITAIFLOW ==="
ls -lad /workspace/gitaiflow
ls -lad /workspace/gitaiflow/.git

echo
echo "=== GITAIFLOW ROOT ==="
git -C /workspace/gitaiflow rev-parse --show-toplevel

echo
echo "=== OTHER REPO ==="
git -C /workspace/djangoplay-cli rev-parse --show-toplevel
'

Expected:

text

/workspace/gitaiflow/.git
/workspace/gitaiflow
/workspace/djangoplay-cli

This check catches an incorrect Docker mount before Claude is involved.

5. Claude Desktop configuration

A local Docker configuration follows this shape:

json

{
  "mcpServers": {
    "gitaiflow-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        "/absolute/path/to/gitaiflow/.mcp.env",
        "-e",
        "MCP_TRANSPORT=stdio",
        "-e",
        "MCP_WORKSPACE=/workspace",
        "-e",
        "MCP_ALLOWED_WORKSPACES=/workspace",
        "-e",
        "GITAIFLOW_BINARY=/app/bin/gitaiflow",
        "-v",
        "/absolute/path/to/home/.gitaiflow:/root/.gitaiflow",
        "-v",
        "/absolute/path/to/parent-workspace:/workspace",
        "-v",
        "/absolute/path/to/parent-workspace/gitaiflow/installers/AOT/v1.1.3/gitaiflow-linux-arm64:/app/bin/gitaiflow:ro",
        "gitaiflow-mcp:local"
      ]
    }
  }
}

Replace all absolute paths with paths on the developer machine.

The /workspace host path must be the parent workspace containing the repositories, not an individual repository, when you want Claude to select multiple repositories.

For your multi-repository layout, this is the intended mapping:

text

/Users/<user>/pyc/missionmq/gl:/workspace

not:

text

/Users/<user>/pyc/missionmq/gl/gitaiflow:/workspace

For AMD64, use:

text

gitaiflow-linux-amd64

No:

text

-p 8080:8080

is required for stdio.

`.mcp.env` and explicit Docker values

Your .mcp.env can contain native host paths, for example:

text

MCP_WORKSPACE=/Users/<user>/pyc/missionmq/gl/
MCP_ALLOWED_WORKSPACES=/Users/<user>/pyc/missionmq/gl/

That is compatible with Docker because the Claude command explicitly overrides them:

text

-e MCP_WORKSPACE=/workspace
-e MCP_ALLOWED_WORKSPACES=/workspace

The effective values inside the container are the explicit Docker values.

6. What Claude should show

On successful startup, Claude should initialize the MCP connection and discover:

text

gitaiflow_change_summary
gitaiflow_last_summary
gitaiflow_changelog
gitaiflow_release_notes
gitaiflow_usage
gitaiflow_list_models

The exact client UI may vary. The protocol evidence is tool discovery and successful invocation.

7. First Claude tool test

Use a deliberately simple prompt:

text

Use the gitaiflow_last_summary tool for the gitaiflow repository and show me the result.
Do not tell me how to run gitaiflow manually.

Expected repository selection:

text

path="gitaiflow"
    ↓
/workspace/gitaiflow
    ↓
Git root = /workspace/gitaiflow

You can test another repository without changing the Claude configuration:

text

Use the gitaiflow_last_summary tool for the djangoplay-cli repository and show me the result.

The important thing is that Claude actually invokes the MCP tool and receives the tool result.

8. Claude MCPB extension

The packaged Claude Desktop extension is a separate local integration path.

Its responsibilities include:

launching MCP locally through stdio
resolving the gitaiflow executable
honoring an explicit Developer Binary Path
using normal production binary locations when no developer override exists
inheriting existing gitaiflow configuration
returning structured binary-resolution errors

It does not replace standalone gitaiflow installation.

9. Developer Binary Path

When configured:

text

/absolute/path/to/gitaiflow

the extension uses that executable directly.

If the configured binary does not exist, the extension must return the configuration error rather than silently falling back.

Expected error semantics:

text

Configured developer gitaiflow binary does not exist: <path>
Remove the Developer Binary Path from the Claude extension settings
to use the production binary automatically.

10. Normal production binary resolution

When Developer Binary Path is empty, normal production locations are:

text

macOS / Linux
    ~/.local/bin/gitaiflow
    /usr/local/bin/gitaiflow

Windows
    %LOCALAPPDATA%\Programs\gitaiflow\gitaiflow.exe

The extension does not automatically select:

text

./bin/gitaiflow

A binary installed through this path is verified against a signed checksum before the extension trusts it — see Release signing.

11. Empty optional configuration

Claude Desktop can pass:

text

${user_config.binary_path}

when the optional setting is empty.

The launcher treats that unresolved literal as unset.

Therefore:

text

explicit developer path
    → use it

empty/unresolved developer path
    → normal production binary resolution

12. AI configuration

The extension continues to use:

text

~/.gitaiflow/config.env

for:

text

AI_PROVIDER
AI_API_KEY
AI_BASE_URL
AI_MODEL

Workspace paths and developer binary paths do not belong there.

13. Claude verification checklist

text

[ ] End-user installation path is understood
[ ] Developer Docker stdio works without Claude
[ ] Parent multi-repository workspace is mounted
[ ] selected repository has its own .git
[ ] Claude launches the Docker process
[ ] MCP initialization succeeds
[ ] six tools are discovered
[ ] gitaiflow_last_summary can be invoked for gitaiflow
[ ] another repository can be selected without changing the Docker mount
[ ] Claude receives the result
[ ] explicit Developer Binary Path works
[ ] missing Developer Binary Path produces structured error
[ ] normal production binary resolution works

Only after this gate should the MCP release be considered locally complete.

gitaiflow MCP — Claude Desktop Integration

#1. What Claude Desktop adds

#2. End-user installation

#3. Docker stdio model for developers

#4. Verify Docker stdio outside Claude first

#Verify the actual Docker filesystem before Claude

#5. Claude Desktop configuration

#.mcp.env and explicit Docker values

#6. What Claude should show

#7. First Claude tool test

#8. Claude MCPB extension

#9. Developer Binary Path

#10. Normal production binary resolution

#11. Empty optional configuration

#12. AI configuration

#13. Claude verification checklist

1. What Claude Desktop adds

2. End-user installation

3. Docker stdio model for developers

4. Verify Docker stdio outside Claude first

Verify the actual Docker filesystem before Claude

5. Claude Desktop configuration

`.mcp.env` and explicit Docker values

6. What Claude should show

7. First Claude tool test

8. Claude MCPB extension

9. Developer Binary Path

10. Normal production binary resolution

11. Empty optional configuration

12. AI configuration

13. Claude verification checklist