Local GitHub Mcpserver

本地github mcpserver

用于本地GitHub集成的MCP（模型上下文协议）服务器。此服务器使Claude能够通过安全的本地服务器直接与您的GitHub帐户交互。

目录

1. 特性
2. 先决条件
3. 安装和设置
4. 克劳德集成
5. 可用工具
6. 故障排除

特性

• 🔍 库管理：搜索、创建和获取存储库详细信息
• 📝 问题管理：列出并创建问题
• 🔀 拉取请求管理：列出拉取请求
• 📄 文件操作：从存储库获取文件内容
• 👤 用户信息：获取GitHub用户详细信息
• 🤖 克劳德集成：在Claude对话中直接使用GitHub工具

先决条件

• Python 3.11.9 （兼容性要求）
• GitHub个人访问令牌
• Claude桌面应用程序 （用于集成）
• Git （用于克隆存储库）

______________________________________________________________________

安装和设置

第一步：安装Python 3.11.9

视窗

1. 从以下网址下载Python 3.11.9 python.org
2. 运行安装程序
3. ⚠️ 重要：在安装过程中选中“将Python添加到PATH”
4. 验证安装：

   python --version

预期产量： Python 3.11.9

macOS/Linux（建议使用pyenv）

# Install pyenv if not already installed
curl https://pyenv.run | bash

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

# Restart your terminal, then:
pyenv install 3.11.9
pyenv local 3.11.9
python --version  # Should show Python 3.11.9

______________________________________________________________________

步骤2：克隆存储库

窗户：

cd E:\Workspace\agentic-ai
git clone https://github.com/lmsamarawickrama/local-github-mcpserver.git
cd local-github-mcpserver

macOS/Linux：

cd ~/workspace/agentic-ai
git clone https://github.com/lmsamarawickrama/local-github-mcpserver.git
cd local-github-mcpserver

______________________________________________________________________

步骤3：虚拟环境设置

3.1检查现有虚拟环境

窗户：

# Check if venv directory exists
dir venv

macOS/Linux：

# Check if venv directory exists
ls -la venv

3.2停用现有虚拟环境（如果处于活动状态）

如果你看到 (venv) 或终端提示中的任何其他环境名称：

Windows CMD:

deactivate

Windows PowerShell：

deactivate

macOS/Linux：

deactivate

3.3删除旧虚拟环境（如果存在）

窗户：

# Remove the old venv directory
rmdir /s /q venv

macOS/Linux：

# Remove the old venv directory
rm -rf venv

3.4使用Python 3.11.9创建新的虚拟环境

窗户：

# Ensure you're in the project root directory
cd E:\Workspace\agentic-ai\local-github-mcpserver

# Create virtual environment
python -m venv venv

# Activate the virtual environment
venv\Scripts\activate.bat

# For PowerShell, use:
# venv\Scripts\Activate.ps1

macOS/Linux：

# Ensure you're in the project root directory
cd ~/workspace/agentic-ai/local-github-mcpserver

# Create virtual environment with Python 3.11.9
python3.11 -m venv venv

# Activate the virtual environment
source venv/bin/activate

3.5验证虚拟环境

激活后，您应该看到 (venv) 在命令提示符的开头。

验证Python版本：

python --version

预期： Python 3.11.9

验证您使用的是venv Python：

窗户：

where python

应显示： E:\Workspace\agentic-ai\local-github-mcpserver\venv\Scripts\python.exe

macOS/Linux：

which python

应显示： /path/to/local-github-mcpserver/venv/bin/python

______________________________________________________________________

步骤4：安装依赖项

虚拟环境激活后：

# Upgrade pip to latest version
python -m pip install --upgrade pip

# Navigate to the app directory
cd app

# Install required packages
pip install -r requirements.txt

验证安装：

pip list

您应该看到：

• mcp (>=0.9.0)
• httpx (>=0.27.0)
• 他们的依赖关系

______________________________________________________________________

步骤5：创建和配置GitHub令牌

5.1创建GitHub个人访问令牌

1. 首选https://github.com/settings/tokens
2. 点击 “生成新令牌” → “生成新令牌（经典）”
3. 给它一个描述性的名字： MCP Server Token
4. 设置过期时间（建议：90天，或为方便起见无过期时间）
5. 选择以下范围：

- ✅ repo -完全控制私有存储库 - ✅ user -读取用户配置文件数据 - ✅ read:org -读取组织数据（可选，如果您使用组织） - ✅ workflow -更新GitHub Action工作流（可选）

1. 点击 “生成令牌”
2. ⚠️ 立即复制令牌 -你再也看不到了！

令牌格式示例： ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

5.2设置环境变量

Windows（临时-仅限当前会话）：

set GITHUB_TOKEN=ghp_your_actual_token_here

Windows（永久-系统范围）：

# Method 1: Using setx command
setx GITHUB_TOKEN "ghp_your_actual_token_here"

# Method 2: Using GUI
# 1. Search "Environment Variables" in Windows Start Menu
# 2. Click "Edit the system environment variables"
# 3. Click "Environment Variables" button
# 4. Under "User variables", click "New"
# 5. Variable name: GITHUB_TOKEN
# 6. Variable value: ghp_your_actual_token_here
# 7. Click OK on all dialogs
# 8. Restart your terminal

macOS/Linux（临时-仅限当前会话）：

export GITHUB_TOKEN="ghp_your_actual_token_here"

macOS/Linux（永久）：

对于bash用户：

echo 'export GITHUB_TOKEN="ghp_your_actual_token_here"' >> ~/.bashrc
source ~/.bashrc

对于zsh用户（macOS默认）：

echo 'export GITHUB_TOKEN="ghp_your_actual_token_here"' >> ~/.zshrc
source ~/.zshrc

对于鱼壳用户：

echo 'set -gx GITHUB_TOKEN "ghp_your_actual_token_here"' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

5.3验证令牌是否已设置

窗户：

echo %GITHUB_TOKEN%

macOS/Linux：

echo $GITHUB_TOKEN

您应该看到您的令牌（或至少部分令牌）。如果看不到任何内容或变量名本身，则表示令牌设置不正确。

______________________________________________________________________

步骤6：在本地测试服务器

在与Claude集成之前，请验证服务器是否正常工作。

6.1启动服务器

窗户：

cd E:\Workspace\agentic-ai\local-github-mcpserver
venv\Scripts\activate.bat
cd app
python server.py

macOS/Linux：

cd ~/workspace/agentic-ai/local-github-mcpserver
source venv/bin/activate
cd app
python server.py

6.2预期行为

• 服务器应无错误启动
• 您不会看到太多输出（它正在等待MCP客户端连接）
• 按 Ctrl+C 停止服务器

6.3常见启动错误

错误：“未设置GITHUB_TOKEN环境变量”

• 解决方案：按照步骤5所述设置GITHUB_TOKEN

错误：“没有名为'mcp'的模块”

• 解决方案：确保venv已激活并运行 pip install -r requirements.txt

错误：“ModuleNotFoundError:没有名为'httpx'的模块”

• 解决方案：安装依赖项： pip install -r requirements.txt

______________________________________________________________________

克劳德集成

步骤1：找到Claude桌面配置文件

窗户：

%APPDATA%\Claude\claude_desktop_config.json

完整路径示例：

C:\Users\YourUsername\AppData\Roaming\Claude\claude_desktop_config.json

打开文件夹：

explorer %APPDATA%\Claude

macOS：

~/Library/Application Support/Claude/claude_desktop_config.json

打开文件夹：

open ~/Library/Application\ Support/Claude

Linux：

~/.config/Claude/claude_desktop_config.json

打开文件夹：

xdg-open ~/.config/Claude

______________________________________________________________________

第二步：获取绝对路径

您需要配置的绝对（完整）路径。

从虚拟环境中获取Python路径

窗户：

cd E:\Workspace\agentic-ai\local-github-mcpserver
venv\Scripts\activate.bat
where python

输出示例：

E:\Workspace\agentic-ai\local-github-mcpserver\venv\Scripts\python.exe

macOS/Linux：

cd ~/workspace/agentic-ai/local-github-mcpserver
source venv/bin/activate
which python

输出示例：

/Users/yourusername/workspace/agentic-ai/local-github-mcpserver/venv/bin/python

获取Server.py路径

窗户：

cd E:\Workspace\agentic-ai\local-github-mcpserver\app
echo %CD%\server.py

输出示例：

E:\Workspace\agentic-ai\local-github-mcpserver\app\server.py

macOS/Linux：

cd ~/workspace/agentic-ai/local-github-mcpserver/app
echo "$(pwd)/server.py"

输出示例：

/Users/yourusername/workspace/agentic-ai/local-github-mcpserver/app/server.py

______________________________________________________________________

步骤3：编辑Claude配置

打开 claude_desktop_config.json 在文本编辑器（记事本、VS Code等）中

如果文件不存在，请使用以下内容创建它：

Windows配置示例：

{
  "mcpServers": {
    "github": {
      "command": "E:\\Workspace\\agentic-ai\\local-github-mcpserver\\venv\\Scripts\\python.exe",
      "args": [
        "E:\\Workspace\\agentic-ai\\local-github-mcpserver\\app\\server.py"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_your_actual_token_here"
      }
    }
  }
}

macOS/Linux配置示例：

{
  "mcpServers": {
    "github": {
      "command": "/Users/yourusername/workspace/agentic-ai/local-github-mcpserver/venv/bin/python",
      "args": [
        "/Users/yourusername/workspace/agentic-ai/local-github-mcpserver/app/server.py"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_your_actual_token_here"
      }
    }
  }
}

如果该文件已存在于其他服务器中：

将github服务器添加到现有 mcpServers 对象：

{
  "mcpServers": {
    "existing-server": {
      "command": "...",
      "args": ["..."]
    },
    "github": {
      "command": "/path/to/your/venv/bin/python",
      "args": [
        "/path/to/your/app/server.py"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_your_actual_token_here"
      }
    }
  }
}

重要配置说明：

1. 使用绝对路径 （从根开始的完整路径）
2. 视窗：使用双反睫毛 \\ 在路径
3. 替换 ghp_your_actual_token_here 使用您的实际GitHub令牌
4. 使用您的实际用户名/路径 -不要完全照搬例子
5. JSON必须有效 -如果不确定，请使用JSON验证器
6. Python路径必须来自您的venv -不是系统Python

______________________________________________________________________

步骤4：验证配置

在重新启动Claude之前，请验证您的JSON：

在线验证器：

• 首选https://jsonlint.com/
• 粘贴您的配置
• 点击“验证JSON”

常见的JSON错误：

• 对象之间缺少逗号
• 尾随逗号（最后一项后的逗号）
• 单引号代替双引号
• 无图案的睫毛（使用 \\ 不 \ 在Windows上）

______________________________________________________________________

步骤5：重新启动克劳德桌面

需要完全关闭：

窗户：

1. 右键单击系统托盘（右下角）中的Claude图标
2. 点击“退出”或“退出”
3. 等几秒钟
4. 重新启动克劳德桌面

macOS：

1. 按 Cmd+Q 当克劳德专注的时候
2. 或者：在Dock中右键单击Claude→ Quit
3. 等几秒钟
4. 重新启动克劳德桌面

Linux：

1. 关闭克劳德窗口
2. 确保进程已停止： pkill -f claude
3. 重新启动克劳德桌面

⚠️ 重要：仅仅关上窗户是不够的。您必须完全退出应用程序。

______________________________________________________________________

步骤6：验证Claude中的集成

打开Claude Desktop并开始新的对话。尝试以下测试命令：

测试1：列出您的存储库

Can you list all my GitHub repositories?

测试2：获取用户信息

Get my GitHub user information

测试3：搜索存储库

Search for Python repositories with more than 1000 stars

测试4：获取存储库详细信息

Get details about the repository lmsamarawickrama/local-github-mcpserver

预期行为：

✅ 成功指标：

• Claude用GitHub上的实际数据进行了回应
• 您可以看到存储库名称、星号、描述等。
• 没有关于缺少工具的错误消息

❌ 故障指示器：

• “我无法访问该工具”
• “我无法访问GitHub”
• 有关身份验证的错误消息
• 无响应或超时

______________________________________________________________________

可用工具

集成后，Claude可以使用这些GitHub工具：

1. search_repositories -搜索GitHub存储库
2. get_pository -获取特定存储库的详细信息
3. list_issues -列出存储库的问题
4. 创建_发行 -在存储库中创建新问题
5. list_pull_requests -列出存储库的拉取请求
6. 获取_文件_内容 -从存储库获取文件内容
7. 创建存储库 -创建新存储库
8. get_user -获取GitHub用户的信息

______________________________________________________________________

项目结构

local-github-mcpserver/
├── app/                 
│   ├── server.py         # Main MCP server implementation
│   └── requirements.txt  # Python dependencies
├── README.md             # This file
├── venv/                 # Virtual environment (created during setup)
│   ├── Scripts/          # Windows
│   └── bin/              # macOS/Linux
└── .git/                 # Git repository

______________________________________________________________________