MCP GitHub应用服务器

一个轻量级的MCP（模型上下文协议）服务器，使用GitHub App身份验证而不是个人访问令牌提供GitHub操作。

先决条件

安装了GitHub应用程序，具有内容（读写）和拉取请求（读写”）的存储库权限
所需的环境变量：

- GITHUB_APP_ID -您的GitHub应用程序ID - GITHUB_PRIVATE_KEY -您的GitHub应用程序私钥（PEM格式） - GITHUB_INSTALLATION_ID -您的GitHub应用程序安装ID

工具

服务器实现了标准的MCP协议，并提供了一个工具：

get_token：使用GitHub App身份验证获取用于访问私有存储库的临时GitHub令牌

- 参数： - owner （string，必填）：GitHub存储库所有者/组织 - repo （string，必填）：GitHub存储库名称 - 返回：一个临时的GitHub令牌（有效期约为1小时），可用于Git命令和GitHub REST API调用

是什么 get_token?

这 get_token 该工具生成一个临时的GitHub身份验证令牌，可用于各种Git操作和GitHub API调用。这不仅仅是用于克隆-令牌可用于：

Git操作：

克隆：克隆私有存储库
git推送：将提交推送到远程存储库
拉取：从远程存储库中提取更新
git获取：获取远程分支和标签
任何其他需要身份验证的Git操作

GitHub REST API操作：

创建/管理问题：创建、更新、评论问题
拉取请求：创建、审核、合并拉取请求
存储库管理：列出内容、下载文件、获取存储库信息
发布：创建和管理发布
任何GitHub REST API端点：令牌可用于所有经过身份验证的API操作

令牌格式：

对于Git操作，请在URL中使用标记：

https://x-access-token:@github.com//.git

对于GitHub REST API操作，请使用授权标头中的令牌：

Authorization: Bearer

代理商注意事项：

令牌是临时的，大约1小时后到期
该令牌可用于任何需要身份验证的Git操作（克隆、推送、拉取、获取等）
该令牌还可用于ANY GitHub REST API操作（创建问题、PR、管理转发等）
你不需要打电话 get_token 每个操作单独使用-一个令牌适用于所有Git和API操作
如果操作失败并出现身份验证错误，则令牌可能已过期-只需调用 get_token 再次获得新的代币

此服务器本身不执行Git操作，但提供临时GitHub令牌供标准Git命令使用。

安装

pip install .

用法

Docker使用

从GitHub容器注册表中提取预构建映像：

docker pull ghcr.io/legido-ai/mcp-github-app-auth:latest

对于ARM主机，您可以使用显式的ARM标签：

docker pull ghcr.io/legido-ai/mcp-github-app-auth:arm

或者从源代码本地构建：

docker build . -t mcp-github-app-auth

测试服务器

此服务器实现了模型上下文协议（MCP），该协议要求在执行任何操作之前进行适当的初始化握手。未初始化的直接JSON-RPC请求将被拒绝。

直接JSON-RPC命令与初始化

要测试服务器，您必须手动发送完整的初始化序列：

获取工具：

(
  echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "manual-test", "version": "1.0"}}}'; \
  echo '{"jsonrpc": "2.0", "method": "notifications/initialized"}'; \
  echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}'
) | docker run -i --rm \
  -e GITHUB_APP_ID="$GITHUB_APP_ID" \
  -e GITHUB_PRIVATE_KEY="$GITHUB_PRIVATE_KEY" \
  -e GITHUB_INSTALLATION_ID="$GITHUB_INSTALLATION_ID" \
  ghcr.io/legido-ai/mcp-github-app-auth

得到一个令牌。在这个例子中，我们想为私有Github存储库获取一个令牌https://github.com/my-org/my-private-repo:

(
  echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "manual-test", "version": "1.0"}}}'; \
  echo '{"jsonrpc": "2.0", "method": "notifications/initialized"}'; \
  echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "get_token", "arguments": {"owner": "my-org", "repo": "my-private-repo"}}}'
) | docker run -i --rm \
  -e GITHUB_APP_ID="$GITHUB_APP_ID" \
  -e GITHUB_PRIVATE_KEY="$GITHUB_PRIVATE_KEY" \
  -e GITHUB_INSTALLATION_ID="$GITHUB_INSTALLATION_ID" \
  ghcr.io/legido-ai/mcp-github-app-auth

与MCP客户端一起使用：

该服务器旨在与MCP兼容的客户端一起使用，例如：

克劳德桌面/代码
谷歌Gemini CLI
其他与MCP兼容的AI助手

有关设置说明，请参阅下面的集成部分。

直接JSON-RPC测试注意事项：

MCP在接受请求之前需要一个三步初始化序列：

客户端发送 initialize 请求协议版本和功能
服务器以其功能进行响应
客户端发送 initialized 通知
只有这样，客户端才能发送以下请求 tools/list 或 tools/call

为什么没有初始化的直接命令不起作用：

简单的echo命令绕过初始化序列，并将失败：

WARNING:root:Failed to validate request: Received request before initialization was complete

这是 正确的MCP协议行为上述命令包括协议所需的完整初始化序列。

使用令牌进行Git操作

一旦你有了令牌，你就可以将其用于各种Git操作：

克隆存储库：

git clone https://x-access-token:ghs_tokenhere@github.com/fictional-org/private-repo.git

克隆特定分支：

git clone -b feature-branch https://x-access-token:ghs_tokenhere@github.com/fictional-org/private-repo.git

推送到存储库：

cd private-repo
# Make some changes
git add .
git commit -m "Update files"
git push https://x-access-token:ghs_tokenhere@github.com/fictional-org/private-repo.git main

拉取更新：

git pull https://x-access-token:ghs_tokenhere@github.com/fictional-org/private-repo.git main

获取远程分支：

git fetch https://x-access-token:ghs_tokenhere@github.com/fictional-org/private-repo.git

设置为远程URL:

git remote set-url origin https://x-access-token:ghs_tokenhere@github.com/fictional-org/private-repo.git
# Now you can use regular git push/pull commands
git push origin main

使用代币进行GitHub API操作

该令牌还可以与GitHub的REST API一起用于Git命令之外的各种操作：

创建问题：

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer ghs_tokenhere" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/fictional-org/private-repo/issues \
  -d '{"title":"Found a bug","body":"Description of the issue","labels":["bug"]}'

创建拉取请求：

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer ghs_tokenhere" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/fictional-org/private-repo/pulls \
  -d '{"title":"Amazing new feature","body":"Please pull these changes","head":"feature-branch","base":"main"}'

向问题添加评论：

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer ghs_tokenhere" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/fictional-org/private-repo/issues/1/comments \
  -d '{"body":"This is a comment on the issue"}'

列出存储库内容：

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer ghs_tokenhere" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/fictional-org/private-repo/contents/path/to/directory

从私有存储库下载文件：

curl -H "Authorization: Bearer ghs_tokenhere" \
  -H "Accept: application/vnd.github.v3.raw" \
  -o downloaded-file.txt \
  -L https://api.github.com/repos/fictional-org/private-repo/contents/path/to/file.txt

获取存储库信息：

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer ghs_tokenhere" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/fictional-org/private-repo

列出拉取请求：

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer ghs_tokenhere" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/fictional-org/private-repo/pulls

创建发布：

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer ghs_tokenhere" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/fictional-org/private-repo/releases \
  -d '{"tag_name":"v1.0.0","name":"Release v1.0.0","body":"Description of the release"}'

端到端示例

示例1：克隆存储库

拉取预构建的图像：

docker pull ghcr.io/legido-ai/mcp-github-app-auth:latest

获取GitHub令牌：

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_token", "arguments": {"owner": "fictional-org", "repo": "private-repo"}}}' | \
  docker run -i --rm \
  -e GITHUB_APP_ID="$GITHUB_APP_ID" \
  -e GITHUB_PRIVATE_KEY="$GITHUB_PRIVATE_KEY" \
  -e GITHUB_INSTALLATION_ID="$GITHUB_INSTALLATION_ID" \
  ghcr.io/legido-ai/mcp-github-app-auth:latest

使用返回的令牌克隆存储库：

# Extract the token from the response (example shows ghs_tokenhere)
git clone https://x-access-token:ghs_tokenhere@github.com/fictional-org/private-repo.git

示例2：克隆、修改和推送

获取GitHub令牌：

TOKEN=$(echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_token", "arguments": {"owner": "fictional-org", "repo": "private-repo"}}}' | \
  docker run -i --rm \
  -e GITHUB_APP_ID="$GITHUB_APP_ID" \
  -e GITHUB_PRIVATE_KEY="$GITHUB_PRIVATE_KEY" \
  -e GITHUB_INSTALLATION_ID="$GITHUB_INSTALLATION_ID" \
  ghcr.io/legido-ai/mcp-github-app-auth:latest | \
  jq -r '.result.content[0].text' | grep -oP 'ghs_\w+')

克隆存储库：

git clone https://x-access-token:$TOKEN@github.com/fictional-org/private-repo.git
cd private-repo

进行更改并推送：

echo "# New content" >> README.md
git add README.md
git commit -m "Update README"
git push https://x-access-token:$TOKEN@github.com/fictional-org/private-repo.git main

示例3：使用具有多个操作的令牌

# Get token
TOKEN=$(echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_token", "arguments": {"owner": "fictional-org", "repo": "private-repo"}}}' | \
  docker run -i --rm \
  -e GITHUB_APP_ID="$GITHUB_APP_ID" \
  -e GITHUB_PRIVATE_KEY="$GITHUB_PRIVATE_KEY" \
  -e GITHUB_INSTALLATION_ID="$GITHUB_INSTALLATION_ID" \
  ghcr.io/legido-ai/mcp-github-app-auth:latest | \
  jq -r '.result.content[0].text' | grep -oP 'ghs_\w+')

# Clone repository
git clone https://x-access-token:$TOKEN@github.com/fictional-org/private-repo.git
cd private-repo

# Set remote URL with token for subsequent operations
git remote set-url origin https://x-access-token:$TOKEN@github.com/fictional-org/private-repo.git

# Now you can use regular git commands
git pull origin main
git push origin main
git fetch --all

与Claude Desktop集成

⚠️ 关键：可变膨胀不起作用

Claude Desktop/Code不支持在配置文件中扩展环境变量。

这是克劳德配置系统的一个基本局限性。如果你尝试使用以下变量 $GITHUB_APP_ID克劳德会把他们当作 字面字符串，而不是作为对环境变量的引用。

这意味着：

❌ GITHUB_APP_ID=$GITHUB_APP_ID → Claude传递文字字符串 "$GITHUB_APP_ID" Docker
❌ 这会导致身份验证失败，并出现“无法解析提供的公钥”等错误
❌ MCP服务器收到无效凭据，无法在GitHub上进行身份验证

为什么会发生这种情况： Claude的JSON配置解析器不执行shell风格的变量替换。这 $VARIABLE 语法原封不动地传递给底层命令，导致Docker容器接收文字字符串而不是实际的凭据值。

❌ 此配置不起作用：

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "github": {
          "command": "docker",
          "args": [
            "run",
            "-i",
            "--rm",
            "-e",
            "GITHUB_APP_ID=$GITHUB_APP_ID",    ← Passed as literal "$GITHUB_APP_ID"
            "-e",
            "GITHUB_PRIVATE_KEY=$GITHUB_PRIVATE_KEY",    ← Passed as literal string
            "-e",
            "GITHUB_INSTALLATION_ID=$GITHUB_INSTALLATION_ID",    ← Not expanded
            "ghcr.io/legido-ai/mcp-github-app-auth:latest"
          ]
        }
      }
    }
  }
}

结果： 身份验证失败，因为MCP接收的是文字字符串，而不是您的实际凭据。

选项1：手动配置（不推荐）

您可以手动编辑 ~/.claude.json 使用硬编码值，但这是 不推荐 出于安全原因：

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "github": {
          "command": "docker",
          "args": [
            "run",
            "-i",
            "--rm",
            "-e",
            "GITHUB_APP_ID=123456",
            "-e",
            "GITHUB_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----\n...",
            "-e",
            "GITHUB_INSTALLATION_ID=78910",
            "ghcr.io/legido-ai/mcp-github-app-auth:latest"
          ]
        }
      }
    }
  }
}

✅ 选项2：自动设置脚本（推荐）

为什么你需要这个脚本：

由于Claude无法展开变量，您需要一个外部脚本来：

读取环境变量($GITHUB_APP_ID等等）
提取其实际值
把这些文字值写进克劳德的 ~/.claude.json 配置文件

此脚本自动化了该过程，是 推荐解决方案 用于与Claude一起设置MCP服务器。

脚本：

此脚本可在或者可以从下面复制：

#!/bin/bash
#
# Setup script for configuring GitHub MCP server in Claude Code
# This script properly expands environment variables when adding the MCP server configuration
#

set -e

echo "Configuring GitHub MCP server for Claude Code..."

# Check if required environment variables are set
if [ -z "$GITHUB_APP_ID" ] || [ -z "$GITHUB_INSTALLATION_ID" ] || [ -z "$GITHUB_PRIVATE_KEY" ]; then
    echo "ERROR: Missing required environment variables!"
    echo "Please ensure the following environment variables are set:"
    echo "  - GITHUB_APP_ID"
    echo "  - GITHUB_INSTALLATION_ID"
    echo "  - GITHUB_PRIVATE_KEY"
    exit 1
fi

# Check if Python is available
if ! command -v python3 &> /dev/null; then
    echo "ERROR: python3 is required but not found in PATH"
    exit 1
fi

# Ensure .claude.json exists
if [ ! -f "$HOME/.claude.json" ]; then
    echo "Creating $HOME/.claude.json..."
    echo '{}' > "$HOME/.claude.json"
fi

# Use Python to safely update the JSON configuration with expanded environment variables
python3 " https://api.github.com/app/installations`

#### 如何手动测试配置

要在配置Claude之前验证您的设置是否有效：

1. Set environment variables

export GITHUB_APP_ID="your-app-id" export GITHUB_INSTALLATION_ID="your-installation-id" export GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY----- ... -----END RSA PRIVATE KEY-----"

2. Test the MCP server directly

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_token", "arguments": {"owner": "legido-ai", "repo": "tasks"}}}' | \ docker run -i --rm \ -e GITHUB_APP_ID="$GITHUB_APP_ID" \ -e GITHUB_PRIVATE_KEY="$GITHUB_PRIVATE_KEY" \ -e GITHUB_INSTALLATION_ID="$GITHUB_INSTALLATION_ID" \ ghcr.io/legido-ai/mcp-github-app-auth:latest

3. You should get a response with a token like:

{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"GitHub token for legido-ai/tasks: ghs_..."}]}}


如果这有效，则您的凭据是正确的，您可以继续进行Claude配置。

## 测试

### 使用Make（推荐）

make test-mcp-validation


这将运行Github MCP验证测试，该测试验证服务器是否正确响应了完整的MCP初始化握手，并给出了正确的JSON-RPC响应。

**注：** 测试需要设置以下环境变量：

- `GITHUB_APP_ID`
- `GITHUB_PRIVATE_KEY`
- `GITHUB_INSTALLATION_ID`

该测试会自动检测您的系统架构，并使用适当的Docker镜像标签(`arm` 对于aarch64， `latest` 对于其他架构）。

### 与docker openclaw集成

此测试作为docker openclaw的一部分自动执行 `full-test` 套房通过 `test-github-app-auth-mcp-validation` 目标。

### 使用pytest

使用以下工具运行单元测试：

python3 -m pytest tests/ -v


## 安全说明

- 安装令牌将在大约1小时后过期
- 服务器自动缓存和刷新令牌

MCP GitHub App Auth

快速接入

详细介绍