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 supportissues.ts: Issue management operations with CRUD functionalityprojects.ts: Comprehensive GitHub Projects v2 operations with full lifecycle managementrepositories.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
.graphqlfiles as TypeScript modules
Configuration Files
Essential configuration files that control the build process and project setup:
package.json: Project metadata, dependencies, and build scriptstsconfig.json: TypeScript compiler settings for ES2022 target with NodeNext modulescodegen.ts: GraphQL Code Generator configuration for auto-generating types from GitHub's schemabuild.ts: Custom esbuild configuration with GraphQL file handling pluginsmithery.yaml: Package configuration for Smithery MCP server registryschema.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
-
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
.envfile 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 permissionsGITHUB_OWNER: GitHub username or organization nameGITHUB_OWNER_TYPE: (Optional) Set touser(default) ororg. Controls whether project listing and management is done for a user or an organization. Set toorgif 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 projectsread:project- Read access of projectsrepo- Full control of private repositoriesrepo:status- Access commit statusrepo_deployment- Access deployment statuspublic_repo- Access public repositoriesrepo:invite- Access repository invitationssecurity_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