sample-mcp-git

Git PR MCP Server

An MCP (Model Context Protocol) server that gives AI coding agents real-time, read-only access to pull request data on a GitLab instance. Works with Claude Desktop, Cursor, GitHub Copilot, Kiro, and any MCP-compatible client.

This is a sample project intended for experimentation and as a reference implementation. See SECURITY.md for the security model and hardening guidance before using it beyond local experimentation.

What It Does

Ask your AI agent questions about your team's PRs — no browser tab-switching:

"Is anyone working on retry logic?"              → search_pull_requests
"Show me the code changes in PR #42"             → get_pr_diff
"Did CI pass?"                                   → get_pipeline_status
"Who still needs to approve?"                    → get_pr_approvals
"Any unresolved review threads?"                 → get_pr_comments
"What's different between my branch and main?"   → compare_branches
"Generate release notes since last Monday"       → generate_release_notes

Tools (10 total)

Tool	Description
list_pull_requests	List all open PRs in a repository
get_pull_request_details	Get full metadata for a specific PR
filter_pull_requests	Filter by author, status, labels, date range
get_pr_diff	Get code diff — files changed, additions/deletions, unified diff content
get_pr_approvals	Approval status — who approved, how many needed, merge-readiness
get_pr_comments	Review discussions — unresolved threads, inline comments
get_pipeline_status	CI/CD pipeline status — passed/failed/running, duration
search_pull_requests	Full-text keyword search across PR titles and descriptions
compare_branches	Compare two branches — commits ahead, files changed, commit messages
generate_release_notes	Auto-generate categorized release notes from merged PRs in a date range

Quick Start

# Clone and install
git clone <repo-url> git-pr-mcp-server
cd git-pr-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Configure
export GITLAB_URL="https://gitlab.example.com"
export GITLAB_TOKEN="<your-gitlab-pat-with-read_api-scope>"

# Run
python -m git_pr_mcp_server

Configuration

All configuration is read from environment variables:

Variable	Required	Default	Description
GITLAB_TOKEN	yes	—	Personal access token, scoped to read_api only
GITLAB_URL	no	https://gitlab.example.com	Base URL of your GitLab instance
SSO_SESSION_URL	no	https://your-sso-provider.example.com/api/session-status	Endpoint that returns HTTP 200 while the SSO session is valid
SSO_COOKIE_PATH	no	~/.sso/cookie	Netscape-format cookie file written by your SSO provider's CLI
GIT_PR_MCP_TRANSPORT	no	stdio	stdio or sse
GIT_PR_MCP_LOG_LEVEL	no	info	debug, info, warn, or error

Authentication model

The server authenticates in two layers, which suits GitLab instances fronted by a cookie-based SSO or reverse proxy:

1. Session cookies — loaded from SSO_COOKIE_PATH and validated against SSO_SESSION_URL. This satisfies the proxy in front of GitLab.
2. Personal access token — read from GITLAB_TOKEN. This authenticates to the GitLab API itself.

If your GitLab instance has no SSO proxy in front of it, point SSO_SESSION_URL at any endpoint on your instance that returns HTTP 200 for an authenticated session, or adapt SsoAuthManager in src/git_pr_mcp_server/auth_manager.py to use a token alone.

Connecting to Your AI Agent

Add this to your MCP client config (Claude Desktop, Cursor, Kiro, etc.):

{
  "mcpServers": {
    "git-pr": {
      "command": "/path/to/.venv/bin/python3",
      "args": ["-m", "git_pr_mcp_server"],
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "<your-token>"
      }
    }
  }
}

Architecture

AI Agent (Claude / Copilot / Cursor / Kiro)
  │  MCP JSON-RPC (stdio or SSE)
  ▼
FastMCP Server (10 tools)
  │
  ▼
PR Service (pagination, filtering, diff processing, release notes)
  │
  ▼
Git Provider Client (python-gitlab, 8 API methods)
  │
  ▼
GitLab v4 API (read-only)

All operations are read-only. Credentials are never exposed to the agent.

Security

• Input validation (Pydantic + regex) on all 10 tools
• Credential isolation (env vars + cookie file only)
• Log redaction (key + value pattern matching)
• Error sanitization (agent sees a generic message, logs have detail)
• TLS enforced, HTTPS-only, 10s timeout
• Read-only enforcement (no write tools, token needs read_api scope only)
• Diff truncation (5KB per file to prevent memory exhaustion)

See SECURITY.md for the full security model, trust boundaries, and hardening guidance.

Running Tests

source .venv/bin/activate
pytest -v

Project Structure

src/git_pr_mcp_server/
├── __main__.py              # Entry point
├── server.py                # FastMCP server + 10 tool handlers
├── pr_service.py            # Business logic
├── git_provider_client.py   # python-gitlab wrapper (8 API methods)
├── response_mapper.py       # GitLab MR → PR normalization
├── auth_manager.py          # SSO session + PAT authentication
├── rate_limiter.py          # Quota tracking + backoff
├── logger.py                # Structured JSON + credential redaction
├── models.py                # Pydantic data models
└── schemas.py               # Input validation schemas

Contributing

See CONTRIBUTING.md. This project follows the Amazon Open Source Code of Conduct.

License

Licensed under the MIT-0 License. See LICENSE.