🌿 Gitrama MCP Server

🌿 Gitrama MCP Server

AI-powered Git intelligence for your IDE — smart commits, branch names, PR descriptions, changelogs, and workflow management.

What is this?

Gitrama MCP Server exposes Gitrama's CLI as 10 MCP tools that any AI assistant can use. Instead of typing gtr commit in your terminal, your AI assistant calls the tool directly — analyzing your code changes, generating commit messages, suggesting branch names, and more.

Works with: Cursor · Claude Desktop · Claude Code · Windsurf · VS Code (Copilot) · Zed · any MCP-compatible client

Install (< 60 seconds)

Step 1: Install the package

pip install gitrama-mcp

Or with uv:

uv pip install gitrama-mcp

This installs both the MCP server and the gitrama CLI.

Step 2: Connect to your IDE

Add to .cursor/mcp.json in your project (or global settings):

{
  "mcpServers": {
    "gitrama": {
      "command": "gitrama-mcp"
    }
  }
}

Add to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gitrama": {
      "command": "gitrama-mcp"
    }
  }
}

claude mcp add gitrama gitrama-mcp

Add to .vscode/settings.json:

{
  "mcp": {
    "servers": {
      "gitrama": {
        "command": "gitrama-mcp"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "gitrama": {
      "command": "gitrama-mcp"
    }
  }
}

Add to Zed settings (⌘,):

{
  "context_servers": {
    "gitrama": {
      "command": {
        "path": "gitrama-mcp"
      }
    }
  }
}

Step 3: Done.

Ask your AI: "Commit my staged changes" — and watch it call gitrama_commit.

Tools (11)

Repository Intelligence

Commit Intelligence

Branch Management

PR & Changelog

Stream (Workflow) Management

Tool Details

gitrama_ask

Ask a natural language question about your repository. Gitrama analyzes commit history, file structure, blame data, and diffs to answer.

Parameters:| Parameter | Type | Default | Description ||-----------|------|---------|-------------|| question | string | required | Any question about your repo || scope | string | "auto" | Context: "auto", "branch", "full", or "staged" || model | string | "" | AI model override |

Example prompts:

• "Who owns the auth module?"
• "When did we last change the payment logic?"
• "What's the riskiest file in this repo?"
• "Summarize what happened on this branch"
• "What changed in the last 3 days?"
• "Explain the purpose of src/utils/retry.py"

gitrama_commit

Generate an AI-powered commit message for staged changes.

Parameters:| Parameter | Type | Default | Description ||-----------|------|---------|-------------|| message_type | string | "conventional" | Style: "conventional", "detailed", or "simple" || context | string | "" | Optional context (e.g., "fixing auth bug") || model | string | "" | AI model override (e.g., "gpt-4o", "claude-sonnet-4-20250514") |

Example prompt: "Commit my changes with a conventional message, context: refactoring the payment module"

gitrama_stage_and_commit

Stage files and commit in one step.

Parameters:| Parameter | Type | Default | Description ||-----------|------|---------|-------------|| files | string | "." | Files to stage (. for all, or space-separated paths) || message_type | string | "conventional" | Commit style || context | string | "" | Optional context || model | string | "" | AI model override |

Example prompt: "Stage and commit all my changes"

gitrama_commit_quality

Analyze recent commit message quality.

Parameters:| Parameter | Type | Default | Description ||-----------|------|---------|-------------|| count | int | 10 | Number of commits to analyze (1-50) |

Example prompt: "How good are our last 20 commit messages?"

gitrama_branch_suggest

Get AI-suggested branch names.

Parameters:| Parameter | Type | Default | Description ||-----------|------|---------|-------------|| description | string | required | Task description || model | string | "" | AI model override |

Example prompt: "Suggest a branch name for adding OAuth2 support"

gitrama_pr

Generate a PR description.

Parameters:| Parameter | Type | Default | Description ||-----------|------|---------|-------------|| base | string | "" | Target branch (default: main/master) || model | string | "" | AI model override |

Example prompt: "Write a PR description for this branch"

gitrama_changelog

Generate a changelog.

Parameters:| Parameter | Type | Default | Description ||-----------|------|---------|-------------|| since | string | "" | Start ref (tag, branch, hash) || until | string | "" | End ref (default: HEAD) || format | string | "markdown" | "markdown" or "json" || model | string | "" | AI model override |

Example prompt: "Generate a changelog since v1.1.1"

Configuration

Environment Variables

HTTP Transport (for CI/CD)

GTR_MCP_TRANSPORT=streamable-http GTR_MCP_PORT=8765 gitrama-mcp

Then connect your client to http://localhost:8765/mcp.

Requirements

• Python 3.10+
• Git installed and in PATH
• A Gitrama API key or local Ollama instance

Set your API key:

gtr config --key YOUR_API_KEY

Or use a local model:

gtr config --provider ollama --model llama3

Development

git clone https://github.com/ahmaxdev/gitrama-mcp.git
cd gitrama-mcp
pip install -e ".[dev]"

# Test with MCP Inspector
mcp dev src/gitrama_mcp/server.py

License

MIT — see LICENSE.

Built by Alfonso Harding · gitrama.ai

🌿