GitHub Projects MCP Server

An MCP (Model Context Protocol) server that enables AI agents to create and manage Agile Sprint-based projects using GitHub Projects.

Features

GitHub Projects v2 API: Full support for GitHub's GraphQL Projects v2 API
GitHub Issues: Create, read, and update GitHub issues
GitHub Repositories: Fetch repository details
Type Safety: Built with TypeScript for maximum type safety

Installation

Installing via Smithery

To install GitHub Projects MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install taylor-lindores-reeves/mcp-github-projects --client claude

Usage

Manual Installation

Clone this repository:

git clone https://github.com/taylor-lindores-reeves/mcp-github-projects.git
cd mcp-github-projects

Install dependencies:
```
bun install
```

Create a .env file with your GitHub token:

GITHUB_TOKEN=your_github_personal_access_token
GITHUB_OWNER=your_github_username
GITHUB_OWNER_TYPE=org
ALLOWED_REPOS=owner/repo,another/repo

Build the server:
```
bun run build
```
Configure your MCP client with the following settings:

{
  "mcpServers": {
    "GitHubProjects": {
      "command": "bun",
      "args": [
        "/path/to/your/directory/mcp-github-projects-main/build/index.js"
      ],
      "env": {
        "GITHUB_TOKEN": "your_github_personal_access_token",
        "GITHUB_OWNER": "your_github_username_or_org",
        "GITHUB_OWNER_TYPE": "org",
        "ALLOWED_REPOS": "owner/repo,another/repo"
      }
    }
  }
}

Environment Variables

GITHUB_TOKEN: GitHub Personal Access Token with appropriate permissions
GITHUB_OWNER: GitHub username or organization name
GITHUB_OWNER_TYPE: (Optional) Set to user (default) or org. Controls whether project listing and management is done for a user or an organization. Set to org if your projects live in a GitHub organization.
ALLOWED_REPOS: (Optional) Comma-separated list of allowed repository slugs (e.g. owner/repo,another/repo). All write operations (creating/updating issues, adding items to projects, etc.) are restricted to these repositories. If not set or empty, all repositories are allowed by default.

Example:

GITHUB_TOKEN=your_github_personal_access_token
GITHUB_OWNER=the-troops
GITHUB_OWNER_TYPE=org
ALLOWED_REPOS=the-troops/sms-troopers,manuelbiermann/convo-run

If you try to perform a write operation on a repository not in this list, the server will throw an error and block the action.

GitHub Token Permissions

This MCP server requires a GitHub Personal Access Token (classic) with the following permissions:

project - Full control of projects
read:project - Read access of projects
repo - Full control of private repositories
repo:status - Access commit status
repo_deployment - Access deployment status
public_repo - Access public repositories
repo:invite - Access repository invitations
security_events - Read and write security events

Development

Commands

Build: bun run build
Generate GraphQL types: bun run graphql-codegen

Project Structure

This project is a MCP Server for GitHub's GraphQL API, with focus on Project V2 operations. The codebase provides typed access to GitHub projects functionality through GraphQL.

Available Operations

Projects

Create, read, update, and delete GitHub Projects
Manage project fields, items, and status updates
Convert draft issues to actual issues
Archive and unarchive project items

Issues

Get issue details
Add issues to projects

Repositories

Get repository information

GitHub Projects Manager