Skip to main content
Glama
deenesjakoruzh
jersonmartinez

github-project-management

by jersonmartinez
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

GitHub Project Management MCP Server

MCP CI

自定义 MCP（模型上下文协议）服务器，使 AI 助手能够通过模型上下文协议以编程方式管理 GitHub Project V2 看板。使用 Python 3.12 和 FastMCP 构建，通过 stdio 传输通信，并在独立的 Docker 容器中运行。

位置

project/
├── mcp/                    ← This directory (root-level, independent of the app)
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── server.py           # FastMCP entry point
│   ├── config.py
│   ├── auth.py
│   ├── capabilities.py     # Tool → permission mapping
│   ├── profiles.py         # Multi-target profile system
│   ├── tools/              # MCP tool definitions
│   ├── services/           # Business logic
│   ├── clients/            # GraphQL + gh CLI clients
│   ├── models/             # Pydantic models
│   ├── graphql/            # Query/mutation strings
│   ├── tests/              # Unit + contract tests
│   ├── scripts/            # Validation, preflight, secret scanning
│   │   ├── validate.sh     # ← Run before every push
│   │   ├── preflight.sh    # Environment prerequisites
│   │   ├── scan_secrets.sh # Token pattern detection
│   │   └── smoke_build.sh  # Minimal build verification
│   ├── profiles/           # Target config (.env files, no secrets)
│   ├── docs/               # Detailed documentation
│   ├── LICENSE             # MIT
│   ├── CONTRIBUTING.md
│   └── SECURITY.md

注意：此 MCP 服务器是独立组件，拥有自己的 Dockerfile、依赖项和生命周期。

Related MCP server: my_pm_tools

工作原理

MCP Client → docker run --rm -i github-project-mcp:latest → stdin/stdout JSON-RPC → GitHub API

  1. MCP 客户端调用工具（例如：create_project_item）

  2. 执行 docker run --rm -i github-project-mcp:latest python server.py

  3. 服务器验证身份验证并等待 stdin 上的命令

  4. 客户端通过 stdin 发送 JSON-RPC，通过 stdout 接收响应

  5. 完成后，容器自动销毁（--rm）

Docker — 构建与管理

构建镜像

# Desde la raíz del proyecto
docker build -t github-project-mcp:latest ./mcp

Docker Compose（本地开发）

在本地配置和运行 MCP 的最简单方式：

# 1. Crear tu configuración local (una sola vez)
cp mcp/.env.example mcp/.env
# Editar mcp/.env con tu GITHUB_TOKEN y target (org/repo/project)

# 2. Construir y verificar
cd mcp/
make build
make verify

Makefile 目标

所有目标都在 Docker 内执行 — 无需主机依赖。

cd mcp/
make help         # Mostrar todos los targets disponibles
make build        # Construir imagen Docker
make verify       # Validar auth + scopes + config
make test         # Ejecutar unit tests
make validate     # CI completo (build + syntax + tests + tools + secrets)
make tools        # Contar herramientas registradas (>= 100)
make syntax       # Verificar sintaxis Python
make secrets      # Escanear credenciales en código
make shell        # Shell interactivo dentro del contenedor
make clean        # Eliminar imágenes

注意： 如果主机上没有 make，可以直接使用 Docker 调用目标。例如：docker run --rm --env-file .env github-project-mcp:latest python3 scripts/verify_setup.py

每位贡献者克隆仓库、创建自己的 .env，只需安装 Docker 即可使用 MCP。

验证镜像存在

docker images | grep github-project-mcp

手动测试（冒烟测试）

docker run --rm -i \
  -e GITHUB_TOKEN="<your_token>" \
  github-project-mcp:latest \
  python server.py

服务器将在 stderr 上打印：github-project-management MCP server ready. Authentication validated successfully. 然后等待 stdin 上的 JSON-RPC。按 Ctrl+C 退出。

修改后重建

docker build -t github-project-mcp:latest ./mcp --no-cache

管理脚本

脚本 ./scripts/dev/start.sh 支持 mcp 参数来管理镜像：

./scripts/dev/start.sh mcp build      # Construir/reconstruir la imagen
./scripts/dev/start.sh mcp test       # Ejecutar smoke test
./scripts/dev/start.sh mcp status     # Verificar si la imagen existe

注意：MCP 不是持久化服务。不需要 up/down/restart。每次客户端使用工具时按需启动。

IDE 集成

MCP 兼容任何支持基于 stdio 的 MCP 协议的客户端。 配置因 IDE 而异 — 通用模式为：

{
  "mcpServers": {
    "github-project-management": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "GITHUB_TOKEN",
        "--env-file", "mcp/.env",
        "github-project-mcp:latest",
        "python", "server.py"
      ]
    }
  }
}

有关各 IDE 的具体配置，请参阅 docs/SETUP.md。

已注册工具（100）

核心操作

工具

描述

discover_ids

发现项目/字段 ID

list_project_items

使用过滤器列出项目项

create_project_item

创建 issue 并添加到项目

update_project_item_fields

更新状态、优先级、截止日期

set_estimate

设置故事点估算

archive_project_item

从看板归档项目项

Issue 管理

工具

描述

close_issue

关闭 issue

reopen_issue

重新打开已关闭的 issue

comment_issue

向 issue 添加评论

edit_issue

编辑标题、正文、标签、里程碑、指派人员

add_sub_issue

链接为子 issue

remove_sub_issue

取消链接子 issue

get_issue_detail

获取完整的 issue 详情

search_issues

按查询条件搜索

看板操作

工具

描述

move_to_status

将项目项移动到任意状态列

move_to_done

标记为已完成

move_to_trash

移动到回收站

bulk_update_items

批量更新多个项目项

bulk_close_issues

批量关闭多个 issue

bulk_assign

批量指派多个 issue

规划与工作流

工具

描述

sprint_planning

生成冲刺计划

generate_release_notes

自动生成发布说明

complete_issue

完整完成工作流

daily_standup

生成每日站会报告

sprint_review

冲刺评审摘要

triage_new_issues

自动分类新提案

escalate_overdue

标记逾期项目项

create_epic

创建父项 + 子项

close_sprint

关闭冲刺并移动项目项

元数据

工具

描述

create_milestone

创建 GitHub 里程碑

close_milestone

关闭里程碑

list_milestones

列出里程碑

create_label

创建标签

list_labels

列出标签

get_project_stats

看板统计

get_sprint_summary

当前冲刺指标

架构

Tool Layer (FastMCP tool definitions)
    ↓
Service Layer (business logic, orchestration)
    ↓
Client Layer (GraphQL + gh CLI + caching)
    ↓
GitHub APIs (GraphQL v4 + REST v3)

委派策略

方法

使用时机

gh CLI

Issue CRUD、评论、项目项添加、关闭

自定义 GraphQL

字段更新、归档、发现、子 issue

环境变量

变量

必需

描述

GITHUB_TOKEN

是

GitHub PAT（细粒度或经典）

GH_PROJECT_ORG_NAME

是

GitHub 所有者（组织或用户登录名）

GH_PROJECT_REPO_NAME

是

仓库名称

GH_PROJECT_PROJECT_NUMBER

是

Project V2 看板编号（1–100000）

故障排除

MCP 无法连接

# Verificar que la imagen existe
docker images | grep github-project-mcp

# Si no existe, construir
docker build -t github-project-mcp:latest ./mcp

# Verificar token
echo $GITHUB_TOKEN | head -c 20

重新连接 MCP

如果 MCP 与 IDE 断开连接，请使用相应 MCP 客户端的重新连接选项。

身份验证错误

  • 验证 GITHUB_TOKEN 在容器环境中可用

  • github_pat_*（细粒度）令牌需要权限：Issues（读写）、Projects（读写）、Metadata（读）

  • 经典令牌需要作用域：repo、project、read:org

相关文档

文档

用途

docs/SETUP.md

令牌设置和权限

docs/USAGE.md

工具输入/输出示例

docs/PARAMETERS.md

参数参考

docs/TROUBLESHOOTING.md

常见错误

源位置与同步

此目录（mcp/）是 MCP 包的规范真源。

仓库包含一个同步副本，位于：

  • app/backend/app/mcp/github_project/ — 嵌入后端用于 Docker 构建

同步工作流

  1. 首先在此处（mcp/）进行所有更改。

  2. 将修改的文件复制到嵌入路径：

    cp mcp/<file> app/backend/app/mcp/github_project/<file>

  3. 使用自动化检查验证：

    ./mcp/scripts/check_sync.sh

同步脚本比较所有共享的 .py 文件（排除 __init__.py，因为它在后端副本中有意不同，以及仅基础设施的文件，如 Dockerfile 和 requirements.txt）。CI 在每次推送时运行此检查 — 不一致会导致构建失败。

后端副本中有意不同的文件

文件

原因

__init__.py

后端特定的导入 + 同步源文档

README.md

指回此处；记录复制策略

后端测试套件对嵌入副本进行测试；语法验证必须编译两个目录树。

加固的运行时行为

所有设置使用 GH_PROJECT_ 前缀，并在启动时验证：

设置

默认值

边界 / 行为

GH_PROJECT_TIMEOUT_SECONDS

10

1–120 秒

GH_PROJECT_RETRY_ATTEMPTS

1

0–5；仅读取，变更操作永不重试

GH_PROJECT_RETRY_DELAY_SECONDS

2.0

0–60 秒，指数退避

GH_PROJECT_CACHE_TTL_HOURS

24

1–720 小时

GH_PROJECT_CACHE_PATH

.github_project_cache.json

可配置的本地路径

GH_PROJECT_PAGE_SIZE

100

1–100

GH_PROJECT_MAX_ITEMS

200

1–1,000

GH_PROJECT_MAX_CLI_OUTPUT_CHARS

1,000,000

10,000–10,000,000

元数据缓存以原子方式写入，使用仅所有者权限（0600），拒绝未来时间戳，并且在组织或项目编号不同时不重用。CLI 和 GraphQL 诊断会脱敏令牌类值，并在返回给 MCP 客户端之前进行限制。

仅 Docker 验证

无需主机 Python 工具即可运行验证：

# Compile both source copies through a Python container
tar -C . -cf - mcp app/backend/app/mcp \
  | docker run --rm -i python:3.12-slim sh -c \
    'mkdir -p /tmp/factib && tar -xf - -C /tmp/factib && \
     python -m compileall -q /tmp/factib/mcp /tmp/factib/app/backend/app/mcp'

# Run the backend MCP tests using the existing backend image
tar -C . -cf - app/backend/app app/backend/tests/mcp \
  | docker run --rm -i -e PYTHONPATH=/tmp/factib/app/backend backend:latest sh -c \
    'mkdir -p /tmp/factib && tar -xf - -C /tmp/factib && cd /tmp/factib/app/backend && \
     pytest -q --confcutdir=/tmp/factib/app/backend/tests/mcp tests/mcp'

本地验证（推送前）

在创建 PR 或推送更改之前始终运行。 这在本地镜像 CI 流水线，并在问题到达 GitHub Actions 之前捕获它们。

快速开始

# Full validation (builds image + runs all checks):
./mcp/scripts/validate.sh

# Quick mode (reuses cached image, skips rebuild):
./mcp/scripts/validate.sh --quick

# Auto-fix known issues (e.g., BOM characters):
./mcp/scripts/validate.sh --fix

检查内容

步骤

内容

与 CI 步骤相同

1. BOM

检测 Python 文件中的 UTF-8 BOM 字节

不适用（防止语法错误）

2. 构建

docker build -t github-project-mcp:validate ./mcp

"构建 MCP 镜像"

3. 语法

对镜像内所有 .py 文件执行 ast.parse

"语法检查"

4. 测试

运行 tests/ 中的测试模块

"运行单元测试"

5. 工具

统计已注册工具（必须 >= 100）

"验证工具数量"

6. 密钥

扫描跟踪文件中的令牌模式

不适用（发布前）

可用脚本

脚本

用途

使用时机

scripts/validate.sh

完整 CI 镜像

每次推送/PR 之前

scripts/preflight.sh

前置检查（Docker、令牌、配置）

首次设置或环境更改时

scripts/scan_secrets.sh

密钥模式检测

发布仓库之前

scripts/smoke_build.sh

最小构建 + 工具数量

快速健全性检查

scripts/run_contract_tests.sh

多目标契约套件

结构性更改之后

常见问题与修复

问题

症状

修复

BOM 字符

SyntaxError: invalid non-printable character U+FEFF

./mcp/scripts/validate.sh --fix

镜像未构建

Docker 命令中出现"Image not found"

docker build -t github-project-mcp:latest ./mcp

令牌未设置

预检中出现"No GitHub token found"

export GITHUB_TOKEN=ghp_...

工具数量 < 100

新工具未在 server.py 中注册

在 server.py 中添加 mcp.tool()(your_tool)

完整的 200 项清单（包括已实现和计划中的工作）位于 docs/HARDENING_200.md。

扩展能力套件：60 个附加工具

该服务器共暴露 100+ 个工具：原始 40 个操作工具加上来自 tools/capability_suite.py 的 60 个专项能力。

分组

用途

示例

Issue 与 Markdown 质量

验证、规范化、摘要、模板、打包和审查 issue

validate_issue_markdown、build_issue_template、build_issue_review_checklist

评论系统

创建进度、计划、阻塞和解决评论；列出/搜索/编辑评论

comment_issue_progress、comment_issue_blocker、list_issue_comments

项目报告

健康度、状态、优先级、负责人、截止日期和字段报告

project_health_report、project_due_date_risk、project_field_options_report

项目规划

导出/导入 Markdown、元数据同步计划和按筛选条件的批量计划

project_export_markdown、project_sync_issue_metadata、project_bulk_status_by_filter

战略自动化

冲刺计划、积压排序、风险/依赖报告和干系人更新

plan_next_sprint、prioritize_backlog、generate_risk_register

路线图与决策

变更日志、发布检查清单、路线图、回顾和自动化决策

generate_changelog_from_issues、build_roadmap_markdown、build_sprint_retrospective

可能造成大规模变更的工具默认返回 dry_run 计划。直接评论工具每次调用执行一次可见的评论操作。能力目录在导入时断言 60 个唯一新增项，Docker 验证确认两个源副本中均注册了 100 个 FastMCP 工具。

分发

Docker 镜像

MCP 服务器以独立 Docker 镜像形式分发。本地构建：

docker build -t github-project-mcp:latest ./mcp

CI/CD 流水线

mcp-ci.yaml 工作流在以下情况下自动运行：

  • 推送到 main 且 mcp/ 下的文件发生变更时

  • 涉及 mcp/ 路径的拉取请求

流水线阶段：

  1. 构建 — Docker 镜像构建验证

  2. 语法检查 — 对所有 Python 文件进行 AST 解析

  3. 单元测试 — 执行 pytest 测试套件

  4. 工具数量验证 — 确保注册的工具 ≥100 个

版本管理

此 MCP 服务器遵循语义化版本控制。发布历史请参阅 CHANGELOG.md。

This server cannot be installed

A
license - permissive license
Not graded
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • GitHub

    Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.

  • ToolAPI

    Free public MCP for AI agents — 193 tools, 44 workflows. No API key.

  • LTD MCP

    Project management MCP for AI agents with safe task reads and writes.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jersonmartinez/mcp-github-projects'

If you have feedback or need assistance with the MCP directory API, please join our Discord server