mcp-github-projects

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