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