libra850/github-project-mcp-server

GitHub Projects MCP Server

This is a Model Context Protocol (MCP) server for operating GitHub Projects from AI agents like Claude, Gemini, and other MCP-compatible clients.

Overview

This server uses the Model Context Protocol (MCP) to allow AI agents like Claude and others to operate GitHub Projects. It manipulates GitHub Projects via the GitHub GraphQL API v4, enabling the automation of task management through natural language.

Setup

1. Clone the repository.

   git clone <repository_url>
   cd github_project_mcp
   

2. Install dependencies.

   npm install
   

3. Set up environment variables. Create a .env file in the project root and add the following content:

   # Personal Access Token for operating GitHub Projects (requires `project` scope)
   GITHUB_PAT=your_personal_access_token_here
   
   # The URL of the target GitHub project
   GITHUB_PROJECT_URL=https://github.com/orgs/your-owner/projects/123
   

Running as MCP Server

This server runs as an MCP (Model Context Protocol) server. For development, you can start the server with:

npm run dev

Integration with MCP Clients

This MCP server can be used directly from MCP-compatible AI clients (Claude Code, Cline, and other MCP-compatible clients). To use with MCP clients, add the following configuration to your settings file:

1. Build the Project First, build the project (compile TypeScript to JavaScript) by running the npm run build command.

   npm install
   npm run build
   

   This will generate dist/index.js.

2. Edit the Configuration File Add the following configuration to your MCP client's settings file:

   {
     "mcpServers": {
       "github-project-mcp": {
         "command": "node",
         "args": ["/path/to/your/github_project_mcp/dist/index.js"],
         "env": {
           "GITHUB_PAT": "your_personal_access_token_here",
           "GITHUB_PROJECT_URL": "https://github.com/orgs/your-owner/projects/123"
         }
       }
     }
   }
   

   Field Descriptions:

   • command: Specify the Node.js executable command.
   • args: Specify the absolute path to the dist/index.js file generated in step 1.
   • env.GITHUB_PAT: Set the Personal Access Token for operating GitHub Projects (requires project scope).
   • env.GITHUB_PROJECT_URL: Set the URL of the target GitHub project.

   Important: Ensure that the path for args is specified correctly as an absolute path according to your environment.

Available Tools

The following tools are available as MCP server:

list_projects

Retrieves a list of projects for the owner specified in the environment variables.

• Parameters: None

get_project_details

Retrieves detailed information about the project specified in the environment variables (including custom field definitions).

• Parameters: None

count_project_items

Count all items in the project specified in the environment variables.

• Parameters: None

add_issue_to_project

Adds an existing issue to the project specified in the environment variables.

• Parameters:
  • issueId (string): Issue ID

update_item_status

Updates the status of an item within the project specified in the environment variables.

• Parameters:
  • itemId (string): Item ID
  • statusFieldId (string): Status field ID
  • newStatusOptionId (string): New status option ID

list_sprints

Retrieves a list of Sprints (iterations) configured for the project specified in the environment variables.

• Parameters: None

update_item_sprint

Assigns a specific item to a specified Sprint in the project specified in the environment variables.

• Parameters:
  • itemId (string): Item ID
  • sprintId (string): Sprint ID

get_items_by_status

Get project items filtered by a specific status from the project specified in the environment variables.

• Parameters:
  • status (string): Status to filter by (e.g., "Todo", "In Progress", "Done")

edit_issues

Edit multiple GitHub issues. Can update title, body, state, labels, and add a comment.

• Parameters:
  • issues (array): An array of issues to update. Each object can contain:
    • owner (string): Repository owner
    • repo (string): Repository name
    • issueNumber (number): Issue number
    • title (string, optional): New title for the issue
    • body (string, optional): New body content for the issue
    • state (string, optional): New state for the issue: "OPEN" or "CLOSED"
    • labels (array, optional): A list of labels to add to the issue
    • comment (string, optional): A comment to add to the issue