mcp-server-github
by kogunlowo123
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