# git-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server in Python that connects to GitHub via the REST API.

git-mcp lets Cursor (or any MCP-compatible AI client) talk to GitHub directly — search repos, read files, list issues, inspect pull requests, and more — without copying data into chat manually.

## How it works

1. **Cursor starts the server** as a background process via your MCP config.
2. The server communicates over **stdio** (standard input/output).
3. When you ask something like *“show open issues in my repo”*, Cursor calls a **tool** on the server.
4. The server uses **PyGithub** and your **GitHub token** to call the GitHub REST API and returns JSON to the AI.

```
Cursor / AI  ──stdio MCP──▶  git-mcp server  ──REST API──▶  GitHub
                                    │
                                    └── GITHUB_TOKEN (.env)
```

**Tools** are actions the AI can take. **Resources** (`github://user`, `github://repos`) are read-only context the AI can pull in automatically.

## Features

**Tools**

| Tool | Description |
|------|-------------|
| `get_repository` | Repository metadata |
| `list_branches` | Branch list |
| `get_file_content` | Read a file (or list a directory) |
| `list_commits` | Recent commits |
| `list_issues` | Issues (excludes PRs) |
| `get_issue` | Issue details + comments |
| `create_issue` | Create an issue |
| `list_pull_requests` | Pull request list |
| `get_pull_request` | PR details, reviews, and files |
| `search_repositories` | Repository search |
| `search_code` | Code search |
| `get_user_info` | User profile |

**Resources**

- `github://user` — authenticated user profile
- `github://repos` — repositories you can access

## Setup

### 1. Create a GitHub token

Create a [Personal Access Token](https://github.com/settings/tokens) with scopes needed for your workflow (typically `repo` for private repos, or `public_repo` for public-only).

### 2. Install

```bash
cd git-mcp
python -m venv .venv
pip install -e .
```

Activate the venv if you prefer (optional on Windows):

```bash
# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate
```

On Windows, if `Activate.ps1` is blocked by execution policy, skip activation and use the venv Python directly:

```powershell
.\.venv\Scripts\python.exe -m git_mcp.server
```

Copy `.env.example` to `.env` and set your token:

```bash
cp .env.example .env
```

### 3. Run locally

```bash
git-mcp
# or
python -m git_mcp.server
```

## Cursor configuration

Add to your Cursor MCP settings (`Settings → MCP → Add new MCP server`, or edit `~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "github": {
      "command": "E:\\mission-x\\cursorWork\\git-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "git_mcp.server"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}
```

Adjust the Python path to your virtual environment. You can also rely on a `.env` file in the project root instead of putting the token in `mcp.json`.

## Example tool calls

```
list_issues(owner="octocat", repo="Hello-World", state="open", limit=5)
get_pull_request(owner="octocat", repo="Hello-World", pr_number=1)
search_code(query="FastMCP in:file language:python")
```

Ask in Cursor:

> List the 5 most recent open issues in `myorg/myrepo` and summarize them.

Cursor calls `list_issues`, gets structured JSON back, and summarizes — no manual tab switching.

## git-mcp vs git vs GitHub CLI

| | **git-mcp** | **`git` CLI** | **`gh` CLI** |
|---|---|---|---|
| **Purpose** | AI ↔ GitHub via MCP | Local repo operations | GitHub from terminal |
| **Used by** | Cursor agent automatically | You in terminal | You in terminal |
| **Good for** | Issues, PRs, search, remote files | Commit, push, branch locally | GitHub workflows from shell |

git-mcp is **GitHub API integration for AI**, not a replacement for local `git` commands like `commit` or `push`.

## Requirements

- Python 3.10+
- `mcp` (Python SDK, v1.x)
- `PyGithub`
- `python-dotenv`