MCP Gh Project

MCP GitHub项目管理服务器

用于管理GitHub项目项（卡）的模型上下文协议（MCP）服务器。此服务器使AI助手能够与GitHub Projects v2交互，允许您直接从AI对话中创建、读取、更新和删除项目项。

🤖 演示

🚀 特性

• 列出GitHub项目 -浏览用户、组织或存储库的项目
• 项目管理 -获取详细的项目信息
• 项目操作 -创建、读取、更新和删除项目项
• 支持多种内容类型 -问题、拉取请求和草稿问题
• 现场管理 -更新自定义项目字段
• 安全认证 -使用GitHub个人访问令牌

📋 先决条件

• Python 3.8或更高版本
• 具有适当权限的GitHub个人访问令牌
• 支持的AI工具之一（Claude Desktop/Code、OpenAI Codex、Google Gemini CLI）

🔧 安装

1.克隆存储库

git clone https://github.com/your-username/mcp-gh-project.git
cd mcp-gh-project

2.设置虚拟环境

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3.安装依赖项

# Install the package
pip install -e .

# Install development dependencies (optional, for building/testing)
pip install -e ".[dev]"

4.GitHub身份验证

创建GitHub个人访问令牌：

1. 转到GitHub设置→ 开发人员设置→ 个人访问令牌→ 代币（经典）
2. 点击“生成新令牌（经典）”
3. 选择范围：

- repo （用于访问存储库） - project （用于项目管理） - read:org （如果使用组织项目）

将令牌设置为环境变量：

export GITHUB_TOKEN="your_github_token_here"

或者创建一个 .env 文件：

cp .env.example .env
# Edit .env and add your token

🤖 AI工具集成

克劳德桌面和克劳德代码

Claude桌面配置

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%/Claude/claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcp-gh-project": {
      "command": "/path/to/mcp-gh-project/venv/bin/python",
      "args": ["-m", "mcp_gh_project"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here"
      }
    }
  }
}

Claude代码配置

对于Claude Code（Claude.ai/Code），添加到项目的 CLAUDE.md 在MCP设置中进行文件或配置：

{
  "mcpServers": {
    "mcp-gh-project": {
      "command": "python",
      "args": ["-m", "mcp_gh_project"],
      "cwd": "/path/to/mcp-gh-project",
      "env": {
        "GITHUB_TOKEN": "your_github_token_here"
      }
    }
  }
}

OpenAI Codex集成

对于OpenAI Codex或支持MCP的工具，请配置服务器连接：

import mcp
from mcp.client import ClientSession

# Connect to the MCP server
async def connect_to_github_mcp():
    session = ClientSession()
    await session.connect_subprocess(
        command="python",
        args=["-m", "mcp_gh_project"],
        env={"GITHUB_TOKEN": "your_token_here"}
    )
    return session

谷歌Gemini CLI

配置Gemini CLI以使用MCP服务器：

# Install Gemini CLI with MCP support
pip install google-generativeai mcp-client

# Configure MCP server
gemini config set mcp.servers.github.command "python -m mcp_gh_project"
gemini config set mcp.servers.github.env.GITHUB_TOKEN "your_token_here"

或者使用配置文件：

# ~/.gemini/config.yaml
mcp:
  servers:
    github:
      command: "python"
      args: ["-m", "mcp_gh_project"]
      env:
        GITHUB_TOKEN: "your_github_token_here"

🛠️ 可用工具

MCP服务器提供以下工具：

list_projects

列出用户、组织或存储库的GitHub项目。

参数：

• owner （必填）：GitHub用户名或组织名称
• repo （可选）：存储库名称，用于列出特定于存储库的项目

例子：

List all projects for the "microsoft" organization

get_project

获取特定项目的详细信息。

参数：

• project_id （必填）：项目ID

例子：

Get details for project ID "PVT_kwDOBkn5os4ABTQ6"

list_project_items

列出项目中的所有项目（问题、PR、草稿问题）。

参数：

• project_id （必填）：项目ID

例子：

Show all items in project "PVT_kwDOBkn5os4ABTQ6"

create_project_item

在项目中创建新项。

参数：

• project_id （必填）：项目ID
• content_type （必填）：“发布”、“请求”或“草稿”
• content_id （可选）：现有问题/PR的ID（问题/PULL_REQUEST需要）
• title （可选）：草稿问题的标题
• body （可选）：草稿问题的正文内容

例子：

Create a draft issue titled "Fix documentation" in project "PVT_kwDOBkn5os4ABTQ6"

update_project_item

更新项目项的字段值。

参数：

• project_id （必填）：项目ID
• item_id （必填）：项目项ID
• field_updates （可选）：字段名称和值字典

例子：

Update the status field of item "PVTI_lADOBkn5os4ABTQ6zgCc" to "In Progress"

delete_project_item

从项目中删除项目。

参数：

• project_id （必填）：项目ID
• item_id （必填）：项目项ID

例子：

Remove item "PVTI_lADOBkn5os4ABTQ6zgCc" from project "PVT_kwDOBkn5os4ABTQ6"

💡 使用示例

一旦配置了AI工具，您就可以使用自然语言命令：

项目发现

"Show me all projects for the facebook organization"
"List projects in the microsoft/vscode repository"
"What projects does the user octocat have?"

项目管理

"Get details about project PVT_kwDOBkn5os4ABTQ6"
"Show all items in the main project"
"Create a new draft issue called 'Update dependencies' in the project"

项目操作

"Add issue #123 to the project board"
"Move the documentation task to the 'Done' column"
"Remove the outdated feature request from the project"

🔧 发展

运行测试

# Run all tests
npm run test

# Or run individually
python tests/test_server.py
python tests/test_compile.py

装订和格式化

# Check code quality
npm run lint

# Fix auto-fixable issues
npm run lint:fix

# Format code
npm run format

# Type checking
npm run typecheck

建筑

# Install development dependencies first
pip install -e ".[dev]"

# Build distribution packages
npm run build

🐛 故障排除

常见问题

“需要GitHub令牌”错误

• 确保您的 GITHUB_TOKEN 环境变量已设置
• 验证令牌的作用域是否正确(repo, project)
• 检查令牌是否未过期

“找不到项目”错误

• 验证您是否有权访问该项目
• 确保项目ID正确
• 检查项目是否为GitHub Projects v2（非经典项目）

MCP服务器连接问题

• 验证配置中的Python路径
• 检查是否安装了所有依赖项
• 确保在配置中激活了虚拟环境

权限不足

• 验证您的GitHub令牌是否具有必要的权限
• 对于组织项目，请确保您是具有适当访问权限的成员
• 检查存储库特定项目的存储库权限

调试模式

使用调试日志运行服务器：

export LOG_LEVEL=DEBUG
python -m mcp_gh_project

日志

检查MCP客户端日志以了解连接和通信问题：

• 克劳德桌面：检查应用程序日志
• 克劳德代码：查看开发人员控制台
• 自定义实现：启用MCP客户端日志记录

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🤝 贡献

欢迎投稿！请随时提交拉取请求。

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

📧 支持

有关支持和问题：

• 在GitHub上打开一个问题
• 检查
• 查看 MCP规范

______________________________________________________________________

内置于❤️ 靠近 Qugnition实验室