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

Project Structure

This MCP server is built with a layered architecture that separates concerns and promotes maintainability. The codebase provides typed access to GitHub's GraphQL API with comprehensive error handling and security features.

Directory Overview

├── src/                       # Source code directory
│   ├── index.ts               # MCP server entry point & tool registration
│   ├── operations/            # Business logic layer
│   │   ├── github-client.ts   # GitHub API client wrapper
│   │   ├── issues.ts          # Issue operations & schemas
│   │   ├── projects.ts        # Project v2 operations & schemas
│   │   ├── repositories.ts    # Repository operations & schemas
│   │   └── index.ts           # Operations barrel exports
│   ├── graphql/               # GraphQL queries & mutations
│   │   ├── issues/            # Issue-related GraphQL files
│   │   ├── projects/          # Project-related GraphQL files
│   │   └── repositories/      # Repository-related GraphQL files
│   ├── types/                 # TypeScript type definitions
│   │   ├── github-api-types.ts # Auto-generated GitHub API types
│   │   └── graphql.d.ts       # GraphQL type declarations
│   ├── utils/                 # Utility functions
│   │   └── graphql-loader.ts  # GraphQL file loader utility
│   └── common/                # Shared utilities
│       ├── errors.ts          # Error handling utilities
│       └── utils.ts           # Common helper functions
├── build/                     # Compiled output directory
├── package.json               # Project configuration & dependencies
├── tsconfig.json              # TypeScript compiler configuration
├── codegen.ts                 # GraphQL code generation configuration
├── build.ts                   # Custom build script with GraphQL plugin
├── smithery.yaml              # Smithery package configuration
├── schema.docs.graphql        # GitHub GraphQL schema for code generation
├── .env.example               # Environment variable template
└── .gitignore                 # Git ignore patterns

Key Components

MCP Server Layer (src/index.ts)

The main entry point that configures and starts the MCP server. Registers all available tools with their schemas and handlers, defines reusable prompts for Agile workflows, and manages communication with MCP clients.

Business Logic Layer (src/operations/)

Contains the core business logic that bridges the MCP server interface with GitHub's APIs. Each file focuses on a specific GitHub domain with comprehensive error handling and security through repository allowlisting.

• github-client.ts: Centralized GitHub API client using Octokit with GraphQL and REST support
• issues.ts: Issue management operations with CRUD functionality
• projects.ts: Comprehensive GitHub Projects v2 operations with full lifecycle management
• repositories.ts: Repository information retrieval operations

GraphQL Layer (src/graphql/)

Organizes GraphQL queries and mutations by feature domain, following GitHub's GraphQL API structure. Each .graphql file corresponds to a specific operation, with index files providing clean imports.

Type System (src/types/)

Ensures type safety throughout the application using a hybrid approach:

• Auto-generated types: Created from GitHub's GraphQL schema using GraphQL Code Generator
• Manual declarations: Enable importing .graphql files as TypeScript modules

Configuration Files

Essential configuration files that control the build process and project setup:

• package.json: Project metadata, dependencies, and build scripts
• tsconfig.json: TypeScript compiler settings for ES2022 target with NodeNext modules
• codegen.ts: GraphQL Code Generator configuration for auto-generating types from GitHub's schema
• build.ts: Custom esbuild configuration with GraphQL file handling plugin
• smithery.yaml: Package configuration for Smithery MCP server registry
• schema.docs.graphql: GitHub's GraphQL schema used for type generation
• .env.example: Template showing required environment variables

Architectural Flow

MCP Client Request → MCP Server → Operations Layer → GitHub Client → GitHub API
                                       ↓
                               Type Validation (Zod Schemas)
                                       ↓
                               GraphQL Queries/Mutations

The system follows a clear request-response pattern with validation gates at each layer, ensuring type safety from the MCP interface through to the GitHub API while maintaining security through repository allowlisting and comprehensive error handling.

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

1. Clone this repository:

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

2. Install dependencies:

   bun install
   

3. 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
   

4. Build the server:

   bun run build
   

5. 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

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