giantswarm/pro

An MCP server for managing Giant Swarm's project boards on GitHub Projects V2.
Overview
PRO exposes Giant Swarm project boards to AI assistants via the Model Context Protocol. It supports multiple boards:
- **Roadmap Board** (#273) -- Company quarterly goals (rocks), team/SIG/WG issues
- **Customer Board** (#345) -- Customer-related activities and requests from private customer repositories
The server provides tools for listing, filtering, creating, and updating issues on either board, along with per-board schema resources that describe the available fields and their valid values. Field filtering is generic -- the LLM reads the board's schema resource to discover available fields, then passes arbitrary field name/value pairs as filters.
Requirements
- Node.js 20+
- GitHub Personal Access Token with project:write and repo:write scopes
Installation
To make the pro command available globally (required for the MCP client config and self-update), install it into your user path -- no sudo needed:
**Option A: Using nvm or fnm (recommended)**
If you manage Node.js with nvm or fnm, npm's global prefix is already in your home directory:
**Option B: Configure npm's global prefix**
Without a version manager, npm's default global prefix is a system path. Redirect it to a user-local directory:
Make sure ~/.local/bin is in your PATH (add to ~/.bashrc or ~/.zshrc):
Then install:
**Option C: Use the full path in MCP config**
If you prefer not to install globally, point your MCP client config directly at the checkout:
Note: this skips the global binary, so pro --self-update won't be available.
Configuration
HTTP transport authentication
With --transport=streamable-http the server picks one of three modes:
| Mode | Configuration | Who holds the GitHub credential |
| --- | --- | --- |
| Env token | GITHUB_API_TOKEN only | the server (one identity for every caller) |
| OAuth 2.1 | GITHUB_OAUTH_CLIENT_ID + GITHUB_OAUTH_CLIENT_SECRET (+ OAUTH_ISSUER_URL) | this server, acting as authorization server in front of GitHub; each caller signs in through it |
| Bearer-only | OAUTH_BEARER_ONLY=true (+ OAUTH_ISSUER_URL) | the caller: every /mcp request carries a GitHub token as bearer, verified via the GitHub API and used for that request. No /authorize, /token, /register; /.well-known/oauth-protected-resource[/mcp] names https://github.com/login/oauth as the authorization server. Made for an MCP aggregator such as muster that holds the person's GitHub grant itself. |
In the OAuth and bearer-only modes GitHub calls run as the caller, so board
changes are attributed to the person. Scoped tokens (classic OAuth, classic
PAT) must cover repo, project and read:org (a wider scope counts:
admin:org or write:org for read:org); GitHub App user-to-server tokens
and fine-grained PATs have no scopes -- GitHub reports an empty scope list for
them -- and are accepted as they are, GitHub enforcing their permissions on
each call.
Environment Variables
- GITHUB_API_TOKEN (required for stdio and the env-token HTTP mode): GitHub PAT with project:write and repo:write scopes.
- OAUTH_BEARER_ONLY (optional, HTTP transport): true selects the bearer-only mode described above.
- GITHUB_APP_SLUG (optional, bearer-only mode): the slug of the GitHub App whose user access tokens alone are accepted (giantswarm-pro, pro's own App, installed on every repository of the organization). Every write is then the person's own, capped by that App's permissions on the repository at hand; a token of another App, an OAuth App or a PAT is answered 401.
- HTTP_PORT (optional): Port for HTTP transport (default: 8080).
- PRO_VERSION (set by the Helm chart): the version the server reports in its startup log and MCP serverInfo, the image tag the chart deploys. Unset, the server reports the package.json version, which the npm package carries from its release tag; a checkout reports 0.0.0-dev.
Transport Modes
The server supports two transport modes, selected via the --transport flag:
stdio (default)
For local AI client integration (Claude Desktop, Cursor, Continue):