AI导哈

GitHub项目管理服务器

一个提供Claude Desktop与GitHub Projects V2无缝集成的模型上下文协议服务器，支持管理GitHub组织项目、跟踪状态更新和直接从Claude对话执行项目操作。

  • by aditira
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 aditira/github-project-mcp

使用说明

GitHub项目MCP服务器

A. 模型上下文协议（MCP）服务器 它提供了Claude Desktop和GitHub Projects V2之间的无缝集成。此工具使您能够直接从Claude对话中管理GitHub组织项目、跟踪状态更新和执行项目操作。

🌟 特性

项目管理

  • 列出组织项目：从任何GitHub组织获取所有项目
  • 详细项目视图：获取全面的项目信息，包括项目、字段和元数据
  • 创建新项目：设置具有可自定义隐私设置的新项目
  • 搜索项目：在整个组织中按标题查找项目

状态更新

  • 查看状态历史记录：检索任何项目的所有状态更新
  • 创建状态更新：添加新的进度更新，包括时间线和状态跟踪
  • 时间线管理：设置开始日期、目标日期和项目状态

高级功能

  • 实时错误处理：全面的错误报告和调试
  • GraphQL集成：直接访问GitHub强大的GraphQL API
  • 灵活的配置：支持任何GitHub组织
  • 连接测试：内置诊断程序，用于验证设置

🚀 快速开始

先决条件

  • Python 3.8或更高版本
  • Claude桌面应用程序
  • 具有适当权限的GitHub个人访问令牌

安装

  1. 克隆存储库

    git clone https://github.com/yourusername/github-projects-mcp.git
cd github-projects-mcp

  2. 安装依赖项

    pip install -r requirements.txt

  3. 配置环境变量

    cp .env.example .env

    编辑 .env 使用您的凭据：

    GITHUB_TOKEN=your_github_token_here
GITHUB_ORG=your_organization_name

  4. 设置Claude Desktop集成

    复制示例配置：

    cp claude_desktop_config-example.json claude_desktop_config.json

    更新中的路径和凭据 claude_desktop_config.json:

    {
  "mcpServers": {
    "github-projects": {
      "command": "/path/to/your/python",
      "args": ["/path/to/github_projects_mcp.py"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here",
        "GITHUB_ORG": "your_organization_name"
      }
    }
  }
}

  5. 添加到克劳德桌面

    将配置合并到您的Claude Desktop配置文件中（通常位于 %APPDATA%\Claude\claude_desktop_config.json 在Windows或 ~/Library/Application Support/Claude/claude_desktop_config.json macOS）。

GitHub令牌设置

  1. 首选 GitHub设置>个人访问令牌
  2. 点击“生成新令牌（经典）”
  3. 选择以下范围：
    • repo -完全控制私有存储库
    • project -完全控制项目
    • read:org -阅读组织和团队成员
  4. 将生成的令牌复制到您的 .env 文件

📚 可用工具

核心项目工具

get_organization_projects(limit=20, include_closed=False)

使用筛选选项从GitHub组织中检索所有项目。

get_project_details(project_number)

获取有关特定项目的全面信息，包括所有项目、字段和元数据。

create_project(title, description="", public=False)

使用可自定义的设置在组织中创建新项目。

状态管理

get_project_status_updates(project_number, limit=20)

获取包含作者和时间线信息的项目的所有状态更新。

create_status_update(project_id, body, title=None, start_date=None, target_date=None, status="ON_TRACK")

添加新的状态更新，支持：

  • Markdown内容
  • 时间线跟踪
  • 状态指示器(ON_TRACK, AT_RISK, OFF_TRACK, COMPLETE)

实用工具

search_projects(query, limit=20)

在整个组织中按标题搜索项目。

test_connection()

验证服务器设置和到GitHub API的连接。

💡 使用示例

在克劳德桌面

配置后，您可以使用自然语言与GitHub项目进行交互：

“显示我们组织中的所有项目”

I'll fetch all the projects from your GitHub organization.

“获取项目#42的详细信息”

Let me get the comprehensive details for project #42 including all items and fields.

“创建一个名为“Q4营销活动”的新项目”

I'll create a new project with that title in your organization.

“向项目PVT_kwDOBqF-Dc4AKjQt添加状态更新，表示我们正在按计划进行”

I'll add a status update indicating the project is on track.

🛠️ 技术细节

建筑

  • 建立在 FastMCP 最优性能框架
  • 用途 GitHub GraphQL API v4 用于高效的数据检索
  • 实施全面的错误处理和调试
  • 支持基于环境的配置

API兼容性

  • 与GitHub Projects V2完全兼容
  • 处理组织和存储库级别的项目
  • 支持所有主要项目字段类型（文本、单选、迭代）
  • 与GitHub最新模式实时同步

安全

  • 基于令牌的身份验证
  • 环境变量保护
  • 无敏感数据存储
  • 安全的API通信

🔧 配置选项

环境变量

变量 描述 必填 示例
GITHUB_TOKEN GitHub个人访问令牌 是 ghp_xxxxxxxxxxxx
GITHUB_ORG GitHub组织名称 是 Smartelco
DEBUG_MODE 启用调试日志记录 否 false

Claude桌面配置

MCP服务器通过配置文件与Claude Desktop集成。确保路径指向您的Python安装和服务器脚本位置。

🐛 故障排除

常见问题

“未找到GITHUB_TOKEN”

  • 确保您的 .env 文件包含正确的令牌
  • 验证令牌是否具有所需的作用域

“组织无法访问”

  • 检查组织名称拼写
  • 确保您的令牌具有 read:org 许可
  • 确认您是该组织的成员

“GraphQL错误”

  • 更新您的GitHub令牌权限
  • 检查组织是否启用了Projects V2

调试模式

启用调试模式以进行详细日志记录：

DEBUG_MODE=true

有关详细的错误信息，请查看Claude Desktop日志。

🤝 贡献

欢迎投稿！请随时提交拉取请求。对于重大更改，请先打开一个问题来讨论您想要更改的内容。

开发设置

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

📄 许可证

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

🙏 致谢

📞 支持

如果您遇到任何问题或有疑问：

  1. 检查 问题 章节
  2. 查阅上述故障排查指南
  3. 使用有关您问题的详细信息创建新问题

由以下材料制成❤️ Claude Desktop和GitHub项目社区

相关 MCP