github-project-info

github-project-info-mcp

一个用于读取公开 GitHub Projects（v2）看板的 MCP 服务，无需身份验证——包括项目条目级数据（状态、自定义字段、故事点）；GitHub 官方 API 无法在未经身份验证的情况下读取这些数据。

完全通过 stdio 在本地运行（npx -y github-project-info-mcp，无需服务、Cloudflare 或任何基础设施）——这是主要的标准用法。此外还提供浏览器客户端和可自托管的 Cloudflare Worker，作为可选扩展，适用于从客户端 JavaScript 调用的特定场景（参见浏览器用法：无需服务、无需部署）；正常使用 MCP 时两者都不需要，且它们都不是 stdio 服务的运行时依赖项。

另附 Agent Skill——见下文的 Skill。

为什么要开发这个项目

GitHub 官方的 Projects v2 REST API 存在身份验证方面的缺口：

端点	组织所有的项目	用户所有的项目
项目元数据（标题、状态、日期）	✅ 公开项目无需身份验证	✅ 公开项目无需身份验证
项目条目（状态、字段、点数）	✅ 公开项目无需身份验证	❌ 401，即使项目是公开的也一样

这已通过对照 GitHub 当前 API 的实时测试确认，并非仅根据文档推断——完整调查过程见 docs/investigation.md。如果你的项目看板归个人 GitHub 用户账号所有（个人或独立项目的常见情况），目前没有官方且有文档说明的免身份验证方式来读取其中的条目。

此库通过公开的备用方案弥补了用户所有项目的这一缺口：项目看板自身的网页会以 JSON 形式嵌入完整的条目数据，任何公开项目均可免身份验证读取。此工具会改为读取这些数据。

哪些是官方方式，哪些不是

• get_project_metadata——使用 GitHub 官方且有文档说明的 REST API （GET /users|orgs/{owner}/projectsV2/{n}）。稳定、无需身份验证，适用于任何公开项目。
• list_project_items——对于组织所有的项目，使用 GitHub 官方 REST API （根据 GitHub 文档，公开项目无需身份验证）。对于用户所有的项目，则改为读取公开看板页面中嵌入的 JSON（<script id="memex-paginated-items-data">）。 此备用方式未经文档说明，也非官方方式——它依赖 GitHub 当前的页面标记，而非公开发布的 API 契约；如果 GitHub 更改页面标记，此方式可能会在没有通知的情况下失效。
• get_project_item——通过 GitHub 自身网页界面使用的内部端点（github.com/memexes/{projectId}/items）获取单个条目。返回项目中的所有字段，包括批量 list_project_items 无法获取的自定义字段（优先级、故事点）。此方式同样未经文档说明，也非官方方式，存在上述相同注意事项。

如果你需要此工具且了解其中的权衡，可以使用它。如果 GitHub 今后为用户所有的项目发布官方的免身份验证条目 API，请改用该 API——届时本项目对这一用例便不再必要。

安装

作为 MCP 服务（标准方式）：分发和运行 MCP 服务的常规方式是通过 npm + npx，这样无需手动克隆或构建即可启动：

npx -y github-project-info-mcp

（需要先将软件包发布到 npm — 如果你正在维护一个分支，请参阅发布。）

从源代码安装（用于开发，或使用库、Worker、浏览器客户端部分）：

git clone https://github.com/shubhtoy/github-project-info-mcp.git
cd github-project-info-mcp
npm install
npm run build

作为 MCP 服务使用

添加到你的 MCP 客户端配置中（Claude Desktop、Kiro 等）：

{
  "mcpServers": {
    "github-project-info": {
      "command": "npx",
      "args": ["-y", "github-project-info-mcp"]
    }
  }
}

或者，从本地克隆运行，而不是使用已发布的软件包：

{
  "mcpServers": {
    "github-project-info": {
      "command": "node",
      "args": ["/path/to/github-project-info-mcp/dist/index.js"]
    }
  }
}

工具

• get_project_metadata(ownerType, owner, projectNumber) — 项目标题、描述、状态和日期。
• list_project_items(ownerType, owner, projectNumber) — 所有项目条目及其字段（状态、标签、子问题进度等，即看板默认视图中可见的内容）。对于用户所有的项目，状态/选择字段的值会自动解析为易读的名称。此处不包含默认视图之外的自定义字段（优先级、故事点等）——请使用 get_project_item 获取。
• get_project_item(projectId, itemId, owner?, projectNumber?) — 单个项目条目的完整字段数据，包括自定义字段（优先级、故事点等），这些字段不会由 list_project_items 返回 — 已通过实时测试确认：批量端点仅反映看板的当前视图，而此逐条目端点会返回项目中定义的所有字段。通过 get_project_metadata 的 id 字段获取 projectId（普通数字数据库 ID — 不是此端点无法使用的 GraphQL 节点 ID nodeId），通过 list_project_items 获取 itemId。同时传入 owner/projectNumber 可解析自定义字段名称和单选项名称（会多发出一个请求）；不传则会返回原始字段/选项 ID。
• get_project_fields(owner, projectNumber) — 用户所有项目的字段定义，包括单选项名称/颜色（例如：状态：待办/进行中/已完成）和已保存的视图。
• list_user_projects(username) — 列出用户帐户拥有的所有公开项目。完全没有官方 API 支持此功能（项目不是 GitHub Search API 的资源类型）；此工具会读取用户个人资料页的 Projects 选项卡。

浏览器使用方式（无需服务，无需部署）

此库调用的备用端点都不会发送 Access-Control-Allow-Origin，因此浏览器无法直接调用它们 — 请参阅 CORS 说明。src/browser-client.ts 默认通过免费的公共 CORS 代理（AllOrigins）进行转发，无需任何设置即可解决此问题：

import { getProjectItemsBrowser, getProjectMetadataBrowser } from 'github-project-info-mcp/browser'

const metadata = await getProjectMetadataBrowser('users', 'someuser', 4) // no proxy needed — official API already sends CORS headers
const items = await getProjectItemsBrowser('someuser', 4) // routed through the public proxy by default

无需帐户或部署即可立即使用。缺点是你需要依赖第三方代理服务 — 该服务有速率限制，且无法保证正常运行时间。适合原型、演示或低流量页面。

升级方案：自托管 Worker（更可靠，仍然免费）

如果你需要可靠性，请改为部署自己的实例 — 同样使用免费套餐，但由你自行掌控。完整步骤请参阅下方的部署自己的实例；部署完成后，将 URL 传给浏览器客户端，而不是使用默认代理：

const items = await getProjectItemsBrowser('someuser', 4, {
  workerBaseUrl: 'https://your-worker.workers.dev',
})

或者直接调用 Worker 的 HTTP API：

GET /users/:username/projects
GET /projects/:owner/:number/metadata?ownerType=user|org
GET /projects/:owner/:number/items?ownerType=user|org
GET /projects/:owner/:number/fields

这两种方式都不需要密钥或环境变量 — 涉及的所有端点都公开且设计为无需身份验证。

技能

此代码库还附带 SKILL.md，遵循 Agent Skills 格式，以便支持技能的 Agent（Claude、Kiro 等）自动发现何时以及如何使用此 MCP 服务 — 可通过 skills.sh 安装（npx skills add shubhtoy/github-project-info-mcp），也可直接将此代码库提供给 Agent。

发布（维护者）

发布到 npm 是分发 MCP 服务的标准方式——发布后，任何人都可以直接运行 npx -y github-project-info-mcp，无需克隆或构建。要发布新版本：

npm version patch   # or minor/major — bumps package.json AND creates a local git tag
git push --tags
npm publish
gh release create v$(node -p "require('./package.json').version") --generate-notes

npm version 已经会创建 git 标签；git push --tags（或 git push --follow-tags）会推送标签，而 gh release create 会将其创建为 GitHub Release，并根据自上一个标签以来的提交自动生成说明（如有需要，可之后编辑以获得更简洁的摘要）。

package.json 中的 files 字段已限定只打包 dist/、README.md 和 LICENSE——不会发布源代码、测试或开发配置。目前尚未将 prepublishOnly 配置为自动构建；发布前请运行 npm run build，或者添加该钩子以强制执行构建。

此外还有官方的 MCP Registry（撰写本文时处于预览阶段），用于在各个客户端中集中发现 MCP 服务——等此软件包稳定后，也值得通过 mcp-publisher CLI 在此发布。

（可选）部署自己的 Cloudflare Worker

标准 MCP 用法不需要此步骤——仅当你希望浏览器客户端跳过对公共代理的依赖（参见上文浏览器用法），或需要远程（非 stdio）MCP 端点时才需要。本节中的内容都不是通过 npx github-project-info-mcp 或任何常规 MCP 客户端配置运行服务所必需的。

已部署一个演示实例，便于快速测试（不提供 SLA——它使用个人 Cloudflare 账户的免费套餐，可能会下线，也可能在大量使用时触及速率限制；对于任何你依赖的用途，请按照以下说明部署自己的实例）：

• CORS 代理 HTTP API：https://github-project-info-api.shubhmittal-sm.workers.dev
• 远程 MCP 服务：https://github-project-info-mcp.shubhmittal-sm.workers.dev/mcp

要部署自己的实例：

npx wrangler login      # one-time, opens a browser to authorize a free Cloudflare account
npm run worker:deploy       # deploys the CORS-proxy HTTP API
npm run mcp-worker:deploy   # deploys the remote MCP server (Streamable HTTP, at /mcp)

两者均可独立部署到 Cloudflare 免费套餐（每天各 100,000 次请求，无需信用卡），部署成功后会输出可访问的 *.workers.dev URL。部署前请先用 npm run worker:dev / npm run mcp-worker:dev 在本地测试。

作为库使用

import { getProjectMetadata, listProjectItems } from 'github-project-info-mcp/client'

const metadata = await getProjectMetadata('users', 'someuser', 4)
const { items } = await listProjectItems('users', 'someuser', 4)

关于 CORS 的说明

只有用于用户自有项目条目的备用端点（看板页面抓取、memex 单条目端点）没有 CORS 标头——这正是 browser-client.ts 和 worker.ts 存在的原因；请参阅上文浏览器用法，了解两种解决方法。GitHub 官方元数据端点已发送 Access-Control-Allow-Origin: *，无需代理。

局限性

• 仅适用于公开项目。私有项目需要真实身份验证——请对这些项目使用 GitHub 官方 API/SDK/CLI。
• 用户自有条目的备用方案依赖 GitHub 未公开的内部实现；如果 GitHub 更改页面结构，该方案可能会失效。如果出现问题，请提交 issue——若找到修复方法或更好的方案，本仓库会进行更新。
• 看板抓取分页：看板页面会返回 GitHub 针对该项目默认视图中的条目。如果某个项目有条目未包含在默认视图中（例如已归档的条目，或被已保存的视图筛除的条目），则无法通过此方式获取。

安全性

依赖项已固定到已修复已知 npm audit 安全公告的版本（这是撰写本文时的检查结果——在将其用于任何敏感场景前，请自行重新运行 npm audit）。值得注意的是，@modelcontextprotocol/sdk 固定在 1.29.0 或更高版本，该版本修复了 DNS 重绑定防护漏洞（CVE-2025-66414）——此特定安全公告影响直接使用 SDK 原始传输类、绑定到 localhost 且未经身份验证的 HTTP 服务；本仓库的 worker-mcp.ts 通过 agents 软件包自带的 WorkerTransport 在 Cloudflare Workers（而非 localhost）上运行，采用的是不同的代码路径，因此该安全公告的确切前提可能不适用于此处——特此说明以保持透明，并非声称本仓库专门针对该问题经过审计。

许可证

MIT