github-project-info

github-project-info-mcp

認証なしで公開 GitHub Projects（v2）ボードを読み取るための MCP サーバーです。GitHub の公式 API では認証なしで読み取れないボードの、アイテム単位のデータ（ステータス、カスタムフィールド、ストーリーポイント）も取得できます。

stdio を使って完全にローカルで動作します（npx -y github-project-info-mcp。サーバー、Cloudflare、その他のインフラは一切不要）。これが主な標準的な利用方法です。クライアントサイド JavaScript から呼び出す場合に限り、ブラウザクライアントとセルフホスト可能な Cloudflare Worker もオプションの追加機能として含まれています（ブラウザーでの使用方法を参照）。通常の MCP の利用にどちらも必要なく、stdio サーバーの実行時依存関係でもありません。

エージェントスキルとしても提供されています。詳細は以下のスキルを参照してください。

このツールが作られた理由

GitHub の Projects v2 向け公式 REST API には、認証に関する制限があります。

エンドポイント	組織所有のプロジェクト	ユーザー所有のプロジェクト
プロジェクトのメタデータ（タイトル、状態、日付）	✅ 公開プロジェクトなら認証なしで利用可能	✅ 公開プロジェクトなら認証なしで利用可能
プロジェクトのアイテム（ステータス、フィールド、ポイント）	✅ 公開プロジェクトなら認証なしで利用可能	❌ 401。プロジェクトが公開されていても発生

これはドキュメントから推測しただけではなく、現在の GitHub API に対して実際に確認済みです。詳細な経緯はdocs/investigation.mdを参照してください。プロジェクトボードが個人の GitHub ユーザーアカウント（個人または単独プロジェクトでは一般的なケース）に所有されている場合、そのアイテムを認証なしで読み取る、公式かつ文書化された方法はありません。

このライブラリは、公開プロジェクトであれば、プロジェクトボードの Web ページ自体にすべてのアイテムデータが 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">）を読み取る方法にフォールバックします。このフォールバックは文書化されておらず、非公式です。公開 API 契約ではなく、GitHub の現在のページマークアップに依存しているため、GitHub が変更した場合、予告なく動作しなくなる可能性があります。
• get_project_item — GitHub の Web UI 自体が使用する内部エンドポイント（github.com/memexes/{projectId}/items）経由で、単一のアイテムを取得します。カスタムフィールド（Priority、Story Points）を含む、プロジェクトのすべてのフィールドを返します。これらは、上記の一括取得ツールlist_project_itemsでは取得できません。こちらも同様に文書化されていない非公式な方法であり、同じ注意点があります。

必要な場合は、こうしたトレードオフを理解したうえでご利用ください。GitHub がユーザー所有プロジェクトのアイテムを認証なしで取得できる公式 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) — すべての項目とそのフィールド（ステータス、ラベル、サブイシューの進捗など、ボードのデフォルトビューに表示される情報）。ユーザー所有のプロジェクトでは、ステータス／選択フィールドの値は自動的に人が読みやすい名前に解決されます。デフォルトビュー以外のカスタムフィールド（Priority、Story Points など）は含まれません。取得するには get_project_item を使ってください。
• get_project_item(projectId, itemId, owner?, projectNumber?) — 1 つの項目のすべてのフィールドデータ。list_project_items では返されないカスタムフィールド（Priority、Story Points など）も含まれます。実際の動作を確認済みです。一括取得エンドポイントが返すのはボードのアクティブビューに表示される情報のみですが、この項目別エンドポイントはプロジェクトで定義されたすべてのフィールドを返します。projectId には get_project_metadata の id フィールド（通常の数値データベース ID）を指定してください。GraphQL ノード ID の nodeId はこのエンドポイントでは使えません。itemId は list_project_items から取得します。カスタムフィールド名と単一選択オプション名を解決するには owner／projectNumber も渡してください（追加リクエストが 1 回必要です）。省略すると、フィールド ID／オプション ID がそのまま返されます。
• get_project_fields(owner, projectNumber) — ユーザー所有のプロジェクトのフィールド定義。単一選択オプションの名前／色（例：Status：Todo／In Progress／Done）と保存済みビューも含まれます。
• list_user_projects(username) — ユーザーアカウントが所有するすべての公開プロジェクトを一覧表示します。これを行う公式 API はありません（Projects は 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（より高い信頼性、引き続き無料）

高い信頼性が必要な用途では、自分のインスタンスをデプロイしてください。無料枠は同じですが、インスタンスを自分で管理できます。手順の詳細は、以下の独自インスタンスのデプロイ（Cloudflare、無料）を参照してください。デプロイ後は、デフォルトのプロキシの代わりに、ブラウザクライアントへ 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

どちらの方法でも、シークレットや環境変数は必要ありません。関係するすべてのエンドポイントは公開されており、意図的に認証なしで利用できます。

スキル

このリポジトリには、Agent Skills 形式に準拠した SKILL.md も含まれています。スキルに対応するエージェント（Claude、Kiro など）が、この MCP サーバーをいつ、どのように使うかを自動的に検出できます。skills.sh（npx skills add shubhtoy/github-project-info-mcp）経由でインストールするか、このリポジトリをエージェントに直接指定してください。

公開（メンテナー向け）

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 リリースを作成します。リリースには、前回のタグ以降のコミットから自動生成されたリリースノートが含まれます（必要に応じて、後から編集して読みやすくまとめてください）。

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 の無料プランに個別にデプロイできます（それぞれ 1 日あたり 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 が存在する理由です。回避方法については、上記のブラウザーでの使用方法にある 2 つの方法を参照してください。GitHub の公式メタデータエンドポイントはすでに Access-Control-Allow-Origin: * を返すため、プロキシは不要です。

制限事項

• 公開プロジェクトでのみ動作します。プライベートプロジェクトには実際の認証が必要です。その場合は GitHub の公式 API／SDK／CLI を使用してください。
• ユーザー所有アイテムのフォールバックは、文書化されていない GitHub 内部の仕組みに依存しているため、GitHub がページ構造を変更すると動作しなくなる可能性があります。動作しなくなった場合は、issue を作成してください。修正方法やより良い方法が見つかれば、このリポジトリを更新します。
• ボードスクレイピングのページネーション：ボードページには、そのプロジェクトについて GitHub のデフォルトビューに表示されるアイテムが返されます。デフォルトビューから除外されているアイテム（アーカイブ済みのアイテムや、保存済みビューのフィルターで除外されたアイテムなど）は、この方法では表示されません。

セキュリティ

依存関係は、既知の npm audit アドバイザリが修正されたバージョンに固定されています（執筆時点で確認済みです。機密性の高い用途で使用する前に、ご自身でも npm audit を再実行してください）。特に、@modelcontextprotocol/sdk は、DNS リバインディング保護の不備（CVE-2025-66414）を修正した 1.29.0 以降に固定されています。この特定のアドバイザリは、SDK の生のトランスポートクラスを直接使用する、認証されていない localhost バインドの HTTP サーバーに影響します。このリポジトリの worker-mcp.ts は localhost ではなく Cloudflare Workers 上で、agents パッケージ独自の WorkerTransport を介して動作します。これは別のコードパスであるため、このアドバイザリが適用される正確な前提条件は、おそらく該当しません。透明性のために記載しており、このリポジトリがこの問題に対して個別に監査済みであると主張するものではありません。

ライセンス

MIT