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.

Related

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