GitHub MCP Server

一個功能強大的 GitHub MCP (Model Context Protocol) 伺服器,提供與 GitHub API 的完整整合。

功能特色

🚀 GitHub 核心功能

• 倉庫管理:列出、查看和管理 GitHub 倉庫
• 提交歷史:查看和分析 Git 提交記錄
• GitHub Actions:監控和分析 Workflow 運行狀態
• 問題管理:創建、更新和查看 Issues
• Pull Request:管理 PR 生命週期
• 評論功能:在 Issues 和 PR 中發表評論
• 文件讀取:讀取倉庫中的文件內容

安裝和設定

1. 克隆專案

git clone <repository-url>
cd github-mcp

2. 安裝依賴

npm install
# 或
yarn install

3. 環境配置

方式一:環境變數

在你的 ~/.zshrc 或 ~/.bashrc 文件中設定環境變數:

# GitHub 配置
export GITHUB_ACCESS_TOKEN="your_github_access_token"

設定完成後,重新載入環境變數:

source ~/.zshrc  # 或 source ~/.bashrc

方式二:使用 .env 文件

複製 .env.example 為 .env:

cp .env.example .env

編輯 .env 文件並填入你的 GitHub Access Token:

GITHUB_ACCESS_TOKEN=your_github_access_token

4. 編譯和啟動

# 編譯
npm run build

# 開發模式
npm run dev

# 生產模式
npm start

5. Claude 配置

在你的 Claude 設定中加入此 MCP 伺服器:

{
  "mcpServers": {
    "github-mcp": {
      "command": "yarn",
      "args": ["dev"],
      "cwd": "/path/to/github-mcp"
    }
  }
}

使用指南

GitHub 基本操作

列出倉庫

使用 github_get_repositories 工具列出您的 GitHub 倉庫

查看提交歷史

使用 github_get_commits 工具查看倉庫的提交歷史
參數:
- repository: 倉庫標識 (格式: owner/repo)
- sha: 分支名稱 (可選)
- since/until: 時間範圍 (可選)

監控 GitHub Actions

使用 github_get_workflow_runs 工具查看工作流運行狀態
使用 github_get_workflow_run_jobs 工具查看具體任務

管理 Issues 和 PR

使用 github_create_issue 創建新問題
使用 github_create_pull_request 創建 Pull Request

評論功能

使用 github_create_pr_comment 在 PR 中發表評論
使用 github_create_issue_comment 在 Issue 中發表評論

獲取 GitHub Access Token

1. 登入 GitHub
2. 前往 Settings > Developer settings > Personal access tokens > Tokens (classic)
3. 點擊 "Generate new token (classic)"
4. 選擇必要的權限:
   • repo - 完整的倉庫控制權限
   • workflow - 更新 GitHub Actions 工作流
   • read:org - 讀取組織和團隊成員資訊
   • write:discussion - 讀寫討論
5. 生成並複製 Token

支援的工具

倉庫操作

• github_get_repositories - 獲取倉庫列表
• github_get_repository - 獲取倉庫詳情
• github_get_file_content - 讀取文件內容

提交操作

• github_get_commits - 獲取提交歷史
• github_get_commit - 獲取提交詳情

GitHub Actions

• github_get_workflow_runs - 獲取工作流運行列表
• github_get_workflow_run - 獲取工作流運行詳情
• github_get_workflow_run_jobs - 獲取工作流任務
• github_get_job_logs - 獲取任務日誌

Issues

• github_get_issues - 獲取問題列表
• github_get_issue - 獲取問題詳情
• github_create_issue - 創建新問題
• github_get_issue_comments - 獲取問題評論
• github_create_issue_comment - 發表問題評論

Pull Requests

• github_get_pull_requests - 獲取 PR 列表
• github_get_pull_request - 獲取 PR 詳情
• github_create_pull_request - 創建 PR
• github_get_pr_files - 獲取 PR 文件變更
• github_get_pr_comments - 獲取 PR 評論
• github_create_pr_comment - 發表 PR 評論

範例使用案例

CI/CD 監控

1. 查看最近的工作流運行 → github_get_workflow_runs
2. 檢查失敗的任務 → github_get_workflow_run_jobs
3. 分析失敗日誌 → github_get_job_logs
4. 創建修復 Issue → github_create_issue

Pull Request 工作流

1. 查看最近的 PR → github_get_pull_requests
2. 檢查特定 PR → github_get_pull_request
3. 查看文件變更 → github_get_pr_files
4. 添加評論回饋 → github_create_pr_comment

Issue 管理

1. 查看開放的 Issues → github_get_issues
2. 查看特定 Issue → github_get_issue
3. 創建新 Issue → github_create_issue
4. 添加評論 → github_create_issue_comment

故障排除

常見問題

1. GitHub API 連接失敗

   • 檢查 GITHUB_ACCESS_TOKEN 是否正確
   • 確認 Token 有足夠的權限
   • 檢查網絡連接

2. API 速率限制

   • GitHub API 有速率限制
   • 認證用戶:每小時 5000 次請求
   • 未認證用戶:每小時 60 次請求

3. MCP 伺服器無法啟動

   • 檢查 Node.js 版本 (建議 Node.js 18+)
   • 確認所有依賴都已安裝
   • 查看錯誤日誌

日誌和偵錯

伺服器啟動時會在 stderr 輸出日誌:

GitHub MCP server 已啟動

倉庫標識格式

所有需要指定倉庫的操作都使用 owner/repo 格式,例如:

• octocat/Hello-World
• facebook/react
• microsoft/vscode

貢獻指南

歡迎貢獻!請:

1. Fork 此專案
2. 創建功能分支
3. 提交您的變更
4. 創建 Pull Request

授權條款

MIT License - 詳見 LICENSE 文件