# mcp-server-github

An MCP (Model Context Protocol) server that provides tools for interacting with the GitHub API, including repositories, issues, pull requests, code search, branches, and GitHub Actions workflows.

## Architecture

```mermaid
graph TB
    subgraph Client
        style Client fill:#4A90D9,stroke:#2E6BA6,color:#FFFFFF
        MCP_Client["MCP Client"]
    end

    subgraph Server["mcp-server-github"]
        style Server fill:#2ECC71,stroke:#1A9B52,color:#FFFFFF
        Index["index.ts<br/>MCP Server Entry"]
        subgraph Tools
            style Tools fill:#F39C12,stroke:#C67D0A,color:#FFFFFF
            T1["list_repos"]
            T2["create_issue"]
            T3["list_pull_requests"]
            T4["get_file_contents"]
            T5["search_code"]
            T6["create_branch"]
            T7["list_workflows"]
            T8["get_workflow_runs"]
        end
    end

    subgraph External["GitHub API"]
        style External fill:#24292E,stroke:#1B1F23,color:#FFFFFF
        Repos["Repos API"]
        Issues["Issues API"]
        PRs["Pull Requests API"]
        Contents["Contents API"]
        Search["Search API"]
        Git["Git Refs API"]
        Actions["Actions API"]
    end

    MCP_Client -- "stdio transport" --> Index
    Index --> T1 & T2 & T3 & T4 & T5 & T6 & T7 & T8
    T1 --> Repos
    T2 --> Issues
    T3 --> PRs
    T4 --> Contents
    T5 --> Search
    T6 --> Git
    T7 --> Actions
    T8 --> Actions
```

## Installation

```bash
npm install
npm run build
```

## Configuration

| Variable | Description | Required |
|---|---|---|
| `GITHUB_TOKEN` | GitHub personal access token | Yes |

## Usage

### Standalone

```bash
GITHUB_TOKEN=ghp_xxxx npm start
```

### Development

```bash
npm run dev
```

### Docker

```bash
docker build -t mcp-server-github .
docker run -e GITHUB_TOKEN=ghp_xxxx mcp-server-github
```

### MCP Client Configuration

```json
{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxx"
      }
    }
  }
}
```

## Tool Reference

| Tool | Description | Parameters |
|---|---|---|
| `list_repos` | List repositories | `owner?`, `type?`, `sort?` |
| `create_issue` | Create an issue | `owner`, `repo`, `title`, `body?`, `labels?`, `assignees?` |
| `list_pull_requests` | List pull requests | `owner`, `repo`, `state?`, `sort?` |
| `get_file_contents` | Get file contents | `owner`, `repo`, `path`, `ref?` |
| `search_code` | Search code | `query`, `per_page?` |
| `create_branch` | Create a branch | `owner`, `repo`, `branch`, `from_branch?` |
| `list_workflows` | List workflows | `owner`, `repo` |
| `get_workflow_runs` | Get workflow runs | `owner`, `repo`, `workflow_id`, `status?` |

## License

MIT