🌿 Gitrama MCP Server

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

What is this?

Gitrama MCP Server exposes Gitrama's CLI as 15 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, reviewing code, and more.

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

What's new in v1.3.2

• 5 new tools — gitrama_scan, gitrama_diff, gitrama_review, gitrama_status, and gitrama_push

• Version surfaced from health check — gitrama_health now returns the MCP server version so you can confirm exactly what's running

• Interactive HTML diff panel — gitrama_diff launches a browser panel with risk-annotated diffs, churn rates, coupling context, and contributor info overlaid on every changed file

• Push from chat — gitrama_push supports upstream tracking, force-with-lease, and auto-resolves the current branch

• Tool count updated from 10 → 15

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/mcp.json:

{
  "mcpServers": {
    "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 (15)

Health & Diagnostics

Repository Intelligence

Code Review & Diff

Commit Intelligence

Branch & Push Management

PR & Changelog

Stream (Workflow) Management

Tool Details

gitrama_health

Check AI server connectivity and confirm the running MCP server version.

Example prompt: "Run a gitrama health check"

Example output:

✅ AI server is healthy!
   🤖 Model: grok-4.20-reasoning
   🌐 Connected to: https://api.x.ai/v1
 
🔖 Gitrama MCP Server: v1.3.2

gitrama_scan

Run a full structural health scan of the repository. Scores every file for continuity risk, boundary entropy, and recurrence patterns. Results are cached in last_scan.json for use by gtr diff and gtr review.

Example prompt: "Run a full gitrama scan of my repo"

gitrama_diff

Show a risk-annotated diff of current changes. Opens an interactive HTML browser panel with Gitrama's structural intelligence overlaid — risk scores, churn rates, coupling gaps, and contributor context for every changed file.

Parameters:

Example prompts:

• "Show me a diff of my staged changes"

• "Diff my branch against main"

gitrama_review

Run an AI code review on current changes before committing. Returns severity-graded findings — security, correctness, risk, coupling — plus a verdict and suggested commit message.

Parameters:

Example prompts:

• "Review my staged changes"

• "Do a full review of all my uncommitted changes"

gitrama_push

Push the current branch to a remote repository. Uses --force-with-lease for safe force pushes and auto-resolves the current branch if none is specified.

Parameters:

Example prompts:

• "Push my changes"

• "Push this branch and set upstream"

• "Force push the current branch"

gitrama_status

Show the working tree status with AI interpretation of staged, unstaged, and untracked files.

Example prompt: "What's my current git status?"

gitrama_ask

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

Parameters:

Example prompts:

• "Who owns the auth module?"

• "What's the riskiest file in this repo?"

• "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:

Example prompt: "Commit my staged changes"

gitrama_stage_and_commit

Stage files and commit in one step.

Parameters:

Example prompt: "Stage and commit all my changes"

gitrama_unstage

Remove files from the staging area without discarding changes.

Parameters:

Example prompt: "Unstage src/auth.py"

gitrama_branch

Generate an AI-powered branch name from a description and optionally create it.

Parameters:

Example prompts:

• "Create a branch for adding OAuth2 support"

• "Suggest a branch name for fixing the payment timeout, don't create it"

gitrama_pr

Generate a PR description from the diff between the current branch and base.

Parameters:

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

gitrama_changelog

Generate a changelog between refs.

Parameters:

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

Stream Tools

The v1.3.2 Workflow

With all 15 tools connected, your full dev loop runs from chat:

describe intent  →  stream switch
write code
ask gitrama what changed  →  diff (HTML panel)
review before push
commit with AI message
push
PR description generated

No terminal. No manual git commands.

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

Proprietary — see LICENSE.

Built by Alfonso Harding · gitrama.ai

🌿