GitHub Projects MCP Server

A Model Context Protocol (MCP) server for GitHub Projects V2. Enables AI assistants to manage GitHub Projects, items, fields, and views through a standardized interface.

Features

Full GitHub Projects V2 Support: Complete CRUD operations for projects, items, fields, and views
Dual Authentication: Support for both Personal Access Tokens (PAT) and GitHub App authentication
User & Organization Projects: Manage projects for both individual users and organizations
17 Specialized Tools: Comprehensive toolset for all project management operations
Type-Safe: Built with TypeScript for complete type safety
Well Tested: 100% unit test coverage

Quick Start

Installation

npm install @lexmata/github-projects-mcp

Configuration

Set your GitHub token as an environment variable:

export GITHUB_TOKEN=ghp_your_personal_access_token

Or configure GitHub App authentication:

export GITHUB_APP_ID=123456
export GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----..."
export GITHUB_APP_INSTALLATION_ID=12345678

Usage with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "github-projects": {
      "command": "npx",
      "args": ["@lexmata/github-projects-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Running Directly

npx @lexmata/github-projects-mcp

Available Tools

Project Management

Tool	Description
`list_projects`	List projects for a user or organization
`get_project`	Get detailed project information
`create_project`	Create a new project
`update_project`	Update project settings
`delete_project`	Delete a project

Item Management

Tool	Description
`list_project_items`	List all items in a project
`get_project_item`	Get item details
`add_draft_issue`	Add a draft issue to project
`add_existing_issue`	Add existing issue/PR to project
`update_item_field`	Update a field value on an item
`remove_project_item`	Remove an item from project

Field Management

Tool	Description
`list_project_fields`	List all fields in a project
`create_field`	Create a custom field
`update_field`	Update field settings
`delete_field`	Delete a custom field

View Management

Tool	Description
`list_project_views`	List all views in a project
`get_project_view`	Get view details

Documentation

Getting Started - Quick start guide
Authentication - Configure GitHub authentication
Tools Reference - Complete tool documentation
Configuration - All configuration options
Examples - Usage examples

Required GitHub Permissions

For Personal Access Tokens (Classic)

repo - Full control of private repositories
project - Full control of projects

For Fine-grained Personal Access Tokens

Repository permissions:
- Issues: Read and write
- Pull requests: Read and write
Organization permissions:
- Projects: Read and write

For GitHub Apps

Repository permissions:
- Issues: Read and write
- Pull requests: Read and write
Organization permissions:
- Projects: Read and write

Development

Prerequisites

Node.js 18+
pnpm 9+

Setup

# Clone the repository
git clone https://github.com/Lexmata/github-projects-mcp.git
cd github-projects-mcp

# Install dependencies
pnpm install

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Build
pnpm build

# Run in development mode
pnpm dev

Project Structure

src/
├── index.ts          # Entry point
├── server.ts         # MCP server setup
├── config.ts         # Configuration handling
├── auth/             # Authentication providers
├── graphql/          # GraphQL client and queries
├── tools/            # Tool implementations
└── types/            # TypeScript types

Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Model Context Protocol - The protocol specification
MCP SDK - Official MCP SDK
GitHub Projects API - GitHub GraphQL API documentation

@lexmata/github-projects-mcp

Quick Install