Github Projects V2

🚀 GitHub Projects V2 MCP Server

This is a Model Context Protocol (MCP) server that provides tools for managing GitHub Projects V2. It can be used with Claude and other MCP clients. This server interacts with GitHub Projects V2 using the GitHub GraphQL API.

✨ Features

• List and view GitHub Projects V2 of users and their organizations.
• Retrieve project fields and items (issues, pull requests, draft issues) within projects.
• Create issues and add them to projects.
• Create draft issues directly within projects.
• Update the field values of project items.
• Remove items from projects.

🚀 Quick Start

This server can be used with any MCP client, such as Claude Desktop. Add it to your MCP client configuration file (e.g., claude_desktop_config.json).

💻 Usage Examples

Basic Usage

Option 1: Use the Published Package

Here is an example configuration using the uvx command runner:

{
  "mcpServers": {
    "github-projects": {
      "command": "uvx",
      "args": [
        "mcp-github-projects"
      ],
      "env": {
        "GITHUB_TOKEN": "your_pat_here"
      }
    }
  }
}

Replace your_pat_here with your actual GitHub Personal Access Token.

Advanced Usage

Option 2: Run from Source Code

To run the project directly from the source code, follow these steps:

Environment Setup

1. Clone the repository:

git clone git@github.com:Arclio/github-projects-mcp.git
cd github-projects-mcp

2. Create and activate a virtual environment:

uv venv
source venv/bin/activate

3. Install dependencies:

uv pip install -e .

4. Set your GitHub token as an environment variable: Create a GitHub Personal Access Token and grant the necessary permissions: repo, project, and read:org. Run the following command to add the token to the .env file:

cp .env.example .env

Then add the following content to the .env file:

export GITHUB_TOKEN=your_personal_access_token

Using from Source Code

When using from the source code, configure your MCP client as follows:

{
  "mcpServers": {
    "github-projects": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/github-projects-mcp",
        "run",
        "mcp-github-projects"
      ],
      "env": {
        "GITHUB_TOKEN": "your_pat_here"
      }
    }
  }
}

Replace /path/to/github-projects-mcp and your_pat_here with your actual repository path and GitHub Personal Access Token.

📚 Documentation

Available Tools

• list_projects: List GitHub Projects V2 of users or organizations.
• get_project_fields: Retrieve available fields in GitHub Projects V2.
• get_project_items: Retrieve items in projects (supports filtering by status or custom single - select fields).
• create_issue: Create a new GitHub issue.
• add_issue_to_project: Add an existing GitHub issue to a project.
• create_draftIssue: Create a draft issue directly in a project.
• update_field: Update the field values of project items.
• remove_item: Remove an item from a project.

⚠️ Important Note

Please ensure that your GitHub account has the necessary permissions to perform the above operations and always follow GitHub's API usage policy.