GitHub Projects V2 Command & Protocol Server

A Model Context Protocol (MCP) endpoint engineered to interface with and manage GitHub's second-generation Project management system utilizing the GraphQL endpoint. This server exposes capabilities to various MCP consumers, such as Claude interfaces.

Core Functionality

• Inventory retrieval for GitHub Projects V2 across user accounts and organizations.
• Accessing project schema (fields) and associated artifacts (issues, pull requests, draft issues).
• Programmatic generation of new GitHub Issues.
• Direct provisioning of draft issues within specified project boards.
• Modification of attribute values for existing project board entries.
• Archiving/removal of items from project boards.

Deployment and Configuration

This service is intended for linkage with any compliant MCP consumer instance (e.g., Claude Desktop). Integration requires registering the server endpoint within your client's configuration file (e.g., claude_desktop_config.json).

Method A: Utilizing Pre-built Distribution

When leveraging a published utility runner like uvx, the setup is concise:

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

Ensure that your_personal_auth_token_here is substituted with a valid GitHub Personal Access Token (PAT).

Method B: Local Execution from Source

To operate the server directly from the cloned source tree, execute the following initialization sequence:

Prerequisite Setup

1. Clone the repository source code:

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

2. Establish and activate a Python isolated execution environment:

   bash uv venv source venv/bin/activate

3. Install necessary dependencies in editable mode:

   bash uv pip install -e .

4. Configure authentication credentials. First, generate a PAT via GitHub Token Creation Link. Required scopes are: repo, project, and read:org.

   Copy the example environment file and populate the token:

   bash cp .env.example .env

   Then, append or modify the token variable in .env:

   bash export GITHUB_TOKEN=your_actual_personal_access_token

Client Configuration (Local Source)

When running locally, configure your MCP client referencing the path to your source directory:

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

Adjust /absolute/path/to/github-projects-mcp to the real location and provide your requisite PAT.

Exposed Toolkit Reference

• list_projects: Enumerates GitHub Projects V2 for a specified owner (user or organization).
• get_project_fields: Retrieves the structural field definitions for a given GitHub Project V2.
• get_project_items: Fetches the contents of a GitHub Project V2, supporting granular filtering based on state or specific single-select custom attributes.
• create_issue: Formulates and submits a new standard GitHub Issue.
• add_issue_to_project: Associates an extant GitHub Issue with a Project V2.
• update_project_item_field: Modifies the designated field value associated with an item within a project.
• create_draft_issue: Instantiates a non-committed issue directly within the scope of a GitHub Project V2.
• delete_project_item: Removes a specified entry from a GitHub Project V2 instance.

Refer to the server source code for comprehensive documentation on individual tool invocation signatures.

Development Directives

The primary source structure is organized as follows:

• src/github_projects_mcp/: Core package location
• server.py: Contains the MCP server logic and tool definitions.
• github_client.py: Handles all communication protocols with the GitHub GraphQL API.

Contributions should focus on:

1. Implementing robust exception handling across all GraphQL operations.
2. Enforcing strict type hinting for all function signatures and parameters.
3. Maintaining up-to-date documentation concurrent with feature additions.

---

Contextual Note (Business Management Tools): Business management utilities encompass the complete spectrum of applications, controls, quantitative methodologies, and systems utilized by enterprises to navigate shifting market dynamics, sustain competitive parity, and enhance operational effectiveness. These solutions are categorized by functional areas such as planning, process automation, record-keeping, human capital management, and strategic decision support. Modern systems have rapidly evolved, moving from traditional MIS and ERP structures into cloud-native SaaS models, emphasizing the critical need for strategic selection and precise customization of tools to organizational requirements, rather than mere adoption of the newest technology.