github-projects-mcp

An MCP (Model Context Protocol) server that exposes GitHub Projects (v2) operations as tools. It wraps the gh CLI to let AI assistants list, view, create, edit, and archive items on your GitHub project boards.

Prerequisites

• Node.js or Bun
• gh CLI installed and authenticated
• The project scope on your GitHub token — run gh auth refresh -s project if needed

Setup

git clone https://github.com/hiibolt/github-projects-mcp.git
cd github-projects-mcp
npm install   # or: bun install

Usage

Claude Code

Add to your Claude Code MCP config (.claude/settings.json or .claude/settings.local.json):

{
  "mcpServers": {
    "github-projects": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "/path/to/github-projects-mcp/index.ts"],
      "env": {
        "GH_OWNER": "your-github-username-or-org"
      }
    }
  }
}

Other MCP Clients

Any MCP-compatible client can connect via stdio. The server binary is the TypeScript entrypoint run through tsx:

npx tsx index.ts

Configuration

| Environment Variable | Description | Default | |---|---|---| | GH_OWNER | Default GitHub user or org for project operations | @me (authenticated user) |

Tools

Read

| Tool | Description | |---|---| | list_projects | List GitHub Projects for a user or organization | | view_project | View details of a specific project by number | | list_fields | List all fields (columns) in a project — returns field IDs, types, and select options needed for edit_item | | list_items | List items in a project with all their field values |

Write

| Tool | Description | |---|---| | add_item | Add an existing issue or PR to a project by URL | | create_draft_item | Create a new draft issue directly in a project | | edit_item | Update a field value on a project item (text, number, date, single-select, iteration, or clear) | | archive_item | Archive or unarchive a project item |

Example Workflow

A typical workflow for updating a project board item:

1. list_projects — find your project number
2. view_project — get the project ID
3. list_fields — get field IDs and single-select option IDs (e.g., Status options)
4. list_items — find the item ID you want to update
5. edit_item — set the field value using the IDs from above

License

MIT