Skip to main content
Glama
README.md
# 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

TDQS

A3.5/5.0

Scored across 8 tools

Disambiguation5/5

Each tool targets a distinct GitHub resource or action: branches, issues, file contents, workflow runs, pull requests, repos, workflows, and code search. No overlap in purpose.

Naming Consistency5/5

All tool names use a consistent verb_noun pattern in snake_case (e.g., create_branch, list_pull_requests), making them predictable and easy to interpret.

Tool Count5/5

With 8 tools, the set is well-scoped for a GitHub MCP server, covering essential read operations and some write operations without being bloated.

Completeness2/5

Missing critical operations like updating or closing issues, creating or merging pull requests, and managing repositories. The surface has notable gaps for typical GitHub workflows.

Maintenance

ActivityInactive
ResponsivenessNo recent community issues