GitHub Issues MCP Server 使用说明

项目简介

本项目是一个基于 Model Context Protocol (MCP) 的服务器实现，旨在使大型语言模型 (LLM) 能够与 GitHub issues 进行交互。它通过 MCP 协议向 LLM 客户端暴露工具，允许 LLM 查询指定仓库的 issues 列表以及创建新的 issue。

主要功能点

列出 GitHub Issues: 可以获取指定 GitHub 仓库中的 issue 列表。
创建 GitHub Issues: 可以在指定的 GitHub 仓库中创建新的 issue。
错误处理: 提供完善的错误处理机制，帮助用户排查配置和使用问题。
安全认证: 通过 GitHub Personal Access Token 进行身份验证，安全访问 GitHub API。

安装步骤

克隆仓库:

git clone https://github.com/timbuchinger/mcp-github.git
cd mcp-github

安装依赖:

pip install uv
uv venv
source .venv/bin/activate   # Linux/macOS
.venv\Scripts\activate  # Windows
uv pip install -r requirements.txt

配置 GitHub Token: 复制 '.env.template' 文件并重命名为 '.env'，然后编辑 '.env' 文件，填入你的 GitHub Personal Access Token。
```
GITHUB_TOKEN=your_token_here
```
如何创建 GitHub Personal Access Token:
- 访问 GitHub Settings -> Developer settings -> Personal access tokens
- 点击 "Generate new token" -> "Generate new token (classic)"
- 填写 Token 描述，勾选 "repo" 权限，然后点击 "Generate token"
- 复制生成的 Token 并粘贴到 '.env' 文件中的 'GITHUB_TOKEN' 字段。

服务器配置

对于 MCP 客户端，你需要配置连接到此 MCP 服务器的参数。以下是一个典型的 JSON 格式配置示例，你需要将其添加到你的 MCP 客户端配置中：

{
  "serverName": "github-issues",
  "command": "python",
  "args": ["-m", "src.mcp_github.server"]
}

'serverName': 为该服务器实例指定一个名称，例如 "github-issues"，用于在 MCP 客户端中标识和调用。
'command': 启动服务器的命令，通常为 'python'。
'args': 传递给 'command' 的参数列表。 '["-m", "src.mcp_github.server"]' 表示以模块方式运行 'src.mcp_github.server.py' 文件，即启动 GitHub Issues MCP 服务器。

基本使用方法

启动服务器: 在项目根目录下运行命令：
```
python -m src.mcp_github.server
```
服务器启动后，会监听标准输入输出 (stdio) 等待 MCP 客户端的连接和请求。

通过 MCP 客户端调用工具: 在 MCP 客户端中，你可以调用以下工具与 GitHub issues 交互：

'get_issues': 获取 GitHub 仓库的 issues 列表。

参数:
- 'repo': 仓库名称，格式为 "owner/repo" (例如 "octocat/Spoon-Knife")。

示例请求 (JSON-RPC callTool 参数):

{
  "tool_call": "get_issues",
  "tool_arguments": {
    "repo": "octocat/Spoon-Knife"
  }
}

'create_issue': 在 GitHub 仓库中创建新的 issue。

参数:
- 'repo': 仓库名称，格式为 "owner/repo" (例如 "octocat/Spoon-Knife")。
- 'title': issue 的标题。
- 'body' (可选): issue 的详细描述。