What is Mcp Github Projects

mcp-github-projects is an MCP (Model Context Protocol) server that allows AI agents to create and manage Agile Sprint-based projects using GitHub Projects.

Use cases

Use cases include managing Agile sprints, tracking issues, organizing tasks in GitHub Projects, and automating project workflows for development teams.

How to use

To use mcp-github-projects, you can either install it automatically via Smithery or manually by cloning the repository, installing dependencies, setting up environment variables, and configuring your MCP client.

Key features

Key features include full support for GitHub’s GraphQL Projects v2 API, the ability to create, read, and update GitHub issues, fetching repository details, and type safety through TypeScript.

Where to use

mcp-github-projects can be used in software development environments, particularly for teams practicing Agile methodologies and utilizing GitHub for project management.

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

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

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