github-project-info-mcp

An MCP server for reading public GitHub Projects (v2) boards without authentication — including item-level data (status, custom fields, story points) for boards that GitHub's own official API can't read unauthenticated.

Runs entirely locally via stdio (npx -y github-project-info-mcp, no server, no Cloudflare, no infrastructure of any kind) — this is the primary, standard way to use it. A browser client and a self-hostable Cloudflare Worker are also included as optional extras for the specific case of calling this from client-side JavaScript (see Browser usage); neither is needed for normal MCP usage and neither is a runtime dependency of the stdio server.

Also ships as an Agent Skill — see Skill below.

Why this exists

GitHub's official REST API for Projects v2 has an authentication gap:

This is confirmed live against GitHub's current API, not just inferred from docs — see docs/investigation.md for the full trail. If your project board is owned by your personal GitHub user account (the common case for solo/personal projects), there is no official, documented, unauthenticated way to read its items.

This library closes that gap for user-owned projects using a public fallback: the project board's own webpage embeds full item data as JSON, unauthenticated, for any public project. This tool reads that instead.

What's official vs. unofficial

• get_project_metadata — uses GitHub's official, documented REST API (GET /users|orgs/{owner}/projectsV2/{n}). Stable, unauthenticated, works for any public project.
• list_project_items — for org-owned projects, uses GitHub's official REST API (unauthenticated for public projects, per GitHub's docs). For user-owned projects, falls back to reading the public board page's embedded JSON (<script id="memex-paginated-items-data">). This fallback is undocumented and unofficial — it depends on GitHub's current page markup, not a published API contract, and could break without notice if GitHub changes it.
• get_project_item — fetches a single item via an internal endpoint GitHub's own web UI uses (github.com/memexes/{projectId}/items). Returns every field on the project, including custom fields (Priority, Story Points) that the bulk list_project_items above can't see. Also undocumented and unofficial, same caveats as above.

Use this if you need it and understand the tradeoff. If GitHub ever publishes an official unauthenticated items API for user-owned projects, switch to that instead — this project would then be unnecessary for that use case.

Installation

As an MCP server (standard path): the conventional way to distribute and run an MCP server is via npm + npx, so it can be launched with no manual clone/build step:

npx -y github-project-info-mcp

(Requires the package to be published to npm first — see Publishing if you're maintaining a fork.)

From source (for development, or to use the library/Worker/browser-client parts):

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

Usage as an MCP server

Add to your MCP client config (Claude Desktop, Kiro, etc.):

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

Or, running from a local clone instead of the published package:

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

Tools

• get_project_metadata(ownerType, owner, projectNumber) — project title, description, state, dates.
• list_project_items(ownerType, owner, projectNumber) — all items with their fields (status, labels, sub-issue progress, etc — whatever's visible in the board's default view). Status/select field values are resolved to human-readable names automatically for user-owned projects. Custom fields outside the default view (Priority, Story Points, etc) are not included here — use get_project_item for those.
• get_project_item(projectId, itemId, owner?, projectNumber?) — single item's full field data, including custom fields (Priority, Story Points, etc) that list_project_items doesn't return — confirmed live: the bulk endpoint only reflects the board's active view, while this per-item endpoint returns every field defined on the project. Get projectId from get_project_metadata's id field (the plain numeric database ID — NOT nodeId, the GraphQL node ID, which does not work with this endpoint), and itemId from list_project_items. Pass owner/projectNumber too to resolve custom field names and single-select option names (adds one extra request); omit them to get raw field/option IDs instead.
• get_project_fields(owner, projectNumber) — field definitions for a user-owned project, including single-select option names/colors (e.g. Status: Todo/In Progress/Done) and saved views.
• list_user_projects(username) — list all public projects owned by a user account. There's no official API for this at all (Projects aren't a GitHub Search API resource type); this reads the user's profile page Projects tab.

Browser usage (no server, no deploy required)

None of the fallback endpoints this library calls send Access-Control-Allow-Origin, so a browser can't call them directly — see CORS note. src/browser-client.ts solves this with zero setup by default, routing through a free public CORS proxy (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

This works immediately, no account or deploy needed. The tradeoff: you're depending on a third-party proxy service — it's rate-limited and its uptime isn't guaranteed. Fine for prototyping, demos, or low-traffic pages.

Upgrade path: self-hosted Worker (more reliable, still free)

For anything you need to be reliable, deploy your own instance instead — same free tier, but you own it. See Deploying your own instance below for the full steps; once deployed, pass the URL to the browser client instead of using the default proxy:

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

Or call the Worker's HTTP API directly:

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

No secrets or environment variables are needed for either path — every endpoint involved is public and unauthenticated by design.

Skill

This repo also ships SKILL.md, following the Agent Skills format, so agents (Claude, Kiro, etc.) that support skills can discover when and how to use this MCP server automatically — install via skills.sh (npx skills add shubhtoy/github-project-info-mcp) or by pointing an agent at this repo directly.

Publishing (maintainers)

Publishing to npm is the standard distribution path for MCP servers — once published, anyone can run npx -y github-project-info-mcp with no clone/build step. To publish a new version:

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 already creates the git tag; git push --tags (or git push --follow-tags) pushes it, and gh release create turns it into a GitHub Release with auto-generated notes from commits since the last tag (edit them afterward for a cleaner summary if needed).

The files field in package.json is already scoped to ship only dist/, README.md, and LICENSE — no source, tests, or dev config get published. prepublishOnly isn't currently wired to auto-build; run npm run build before publishing, or add that hook if you want it enforced.

There's also an official MCP Registry (in preview as of writing) for centralized discovery across clients — worth publishing there too once this package is stable, via the mcp-publisher CLI.

(Optional) Deploying your own Cloudflare Worker