AI导哈

GitHub项目管理协议服务器

一个用于GitHub Projects的模型上下文协议服务器，提供可扩展的接口以支持其他任务管理器。

  • by artemfomin
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 artemfomin/Github-Projects-MCP

使用说明

GitHub 项目 MCP 服务器

MCP（模型上下文协议）服务器，用于与GitHub Projects协同工作，提供可扩展的接口以支持其他任务管理器。

特点

  • ✅ 抽象接口轻松将GitHub替换为Jira或其他任务管理工具
  • ✅ 弱结合分层架构的纯净设计
  • ✅ 20种工具全面支持工单处理及其关联
  • ✅ 翻译成中文是：✅（这个符号本身没有特定的中文含义，通常在中文环境中，人们会直接使用这个符号来表示“正确”或“确认”的意思，或者根据上下文来解释其含义。）如果非要给这个符号一个中文解释的话，可以理解为“正确”或“确认”。 GraphQL API使用现代的GitHub GraphQL API
  • ✅ 类型安全使用 Pydantic 模型进行完整类型化

建筑学

┌─────────────────────────────┐
│    MCP Server (FastMCP)     │  ← 20 tools для Claude
│  - get_tickets, add_comment │
│  - add_parent, add_blocking │
└──────────┬──────────────────┘
           │
           ▼
┌─────────────────────────────┐
│  TaskManagerInterface (ABC) │  ← Абстрактный слой
│  - All task operations      │     (можно заменить на Jira)
└──────────┬──────────────────┘
           │
           ▼
┌─────────────────────────────┐
│  GitHubProjectsClient       │  ← GitHub реализация
│  - GraphQL API calls        │
└─────────────────────────────┘

安装

1. 安装依赖项

cd github-projects-mcp
uv sync --frozen --dev

或者使用 pip：

pip install -e .

2. 环境设置

创建 .env 基于文件的 .env.example：

cp .env.example .env

编辑 .env 文件：

# GitHub Personal Access Token с правами:
# - repo (full control)
# - project (read:project, write:project)
GITHUB_TOKEN=ghp_your_token_here

# Владелец репозитория
GITHUB_OWNER=my_username

# Название репозитория
GITHUB_REPO=target_repo_name

# Номер проекта (опционально)
GITHUB_PROJECT_NUMBER=1

3. 创建GitHub个人访问令牌

  1. 进入设置 → 开发者设置 → 个人访问令牌 → 令牌（经典）
  2. 生成新令牌（经典版）
  3. 选择权限：
    • ✅ repo （对私有仓库的完全控制）
    • ✅ project （对项目的全面控制）
  4. 将令牌复制到 .env 文件

使用

启动服务器

# Через uv
uv run python -m github_projects_mcp.server

# Или напрямую
python src/github_projects_mcp/server.py

使用MCP Inspector进行测试

mcp dev src/github_projects_mcp/server.py

将打开网页界面以测试所有工具。

可用的工具

工单处理

  1. 获取门票 - 获取工单列表

    • 过滤器：状态、负责人、标签、里程碑、限制

  2. 获取门票 - 根据ID/编号获取一个工单

评论

  1. 获取评论 - 获取工单的评论
  2. 添加评论 - 添加评论

标签

  1. 获取标签 - 获取所有可用标签
  2. 获取工单标签 - 获取特定工单的标签
  3. 添加标签 - 为工单添加标签

状态（或：状态更新）

  1. 更新状态 - 更改工单状态

分支和公关

  1. 添加分支 - 将分支绑定到工单
  2. 添加拉取请求 - 将PR绑定到工单

创建工单

  1. 创建工单 - 创建一个新工单
  2. 创建子任务 - 创建子任务

工单之间的关联

  1. 添加子任务 - 为工单添加子任务
  2. 添加父级 - 设置父工单
  3. 添加被阻止项 - 标记为该工单已被他人锁定
  4. 添加拦截 - 注明该工单会阻塞其他工单

用途

  1. 分配工单 - 为用户分配工单
  2. 分配给自己 - 将工单分配给自己

里程碑

  1. 获取里程碑 - 获取里程碑列表
  2. 添加里程碑 - 将工单添加到里程碑中

项目

  1. 将工单添加到项目中 - 将工单添加到项目中

与Claude Code的集成

添加到配置中

编辑Claude Code的配置（通常 ~/.claude/config.json 或通过用户界面(UI)：

{
  "mcpServers": {
    "github-projects": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/github-projects-mcp",
        "run",
        "python",
        "-m",
        "github_projects_mcp.server"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here",
        "GITHUB_OWNER": "your_github_username",
        "GITHUB_REPO": "your_repo_name"
      }
    }
  }
}

集成测试

添加后，请重启Claude Code并检查可用工具：

You: Show me available MCP tools
Claude: [должен показать 15 инструментов github-projects]

使用示例

You: Get all open tickets from my repository
Claude: [использует get_tickets tool]

You: Add comment "Working on this" to ticket #5
Claude: [использует add_comment tool]

You: Assign ticket #10 to myself
Claude: [использует assign_to_self tool]

测试

设置测试

测试使用您配置的GitHub仓库

# Убедитесь что .env настроен правильно
export GITHUB_TOKEN=your_token
export GITHUB_OWNER=your_github_username
export GITHUB_REPO=your_repo_name

启动测试

# Все тесты
uv run pytest

# С выводом логов
uv run pytest -v

# Конкретный тест
uv run pytest tests/test_github_client.py -k test_get_tickets

开发

添加新的任务管理器

  1. 创建一个新模块（例如， jira/client.py)
  2. 实现 TaskManagerInterface
  3. 更新 server.py 用于使用新客户端
from .jira import JiraClient

# В server_lifespan:
task_manager = JiraClient(
    url=settings.jira_url,
    username=settings.jira_username,
    api_token=settings.jira_token,
)

缩进和格式化

# Форматирование
uv run ruff format .

# Проверка стиля
uv run ruff check .

# Исправление проблем
uv run ruff check . --fix

# Проверка типов
uv run pyright

项目结构

github-projects-mcp/
├── src/
│   └── github_projects_mcp/
│       ├── __init__.py
│       ├── server.py              # MCP server с tools
│       ├── config.py               # Настройки
│       ├── interfaces/
│       │   └── task_manager.py    # Абстрактный интерфейс
│       ├── models/                 # Pydantic модели
│       │   ├── ticket.py
│       │   ├── comment.py
│       │   ├── label.py
│       │   └── milestone.py
│       └── github/                 # GitHub реализация
│           └── client.py
├── tests/
│   ├── conftest.py
│   └── test_github_client.py
├── pyproject.toml
├── .env.example
└── README.md

要求

  • Python 版本 >= 3.10
  • GitHub 个人访问令牌
  • uv（推荐）或 pip

许可证

麻省理工学院（MIT）

作者

你的名字

相关 MCP