GitHub Projects MCP Server

An MCP (Model Context Protocol) server that provides tools for interacting with GitHub Projects via GraphQL API. This repo is managed by the Model Context Protocol (MCP) and is designed to work seamlessly with Claude Desktop. Written by ProRanked.

Features

Project Management

Create new projects for repositories or organizations
List projects for repositories and organizations
Get detailed project information including fields
List items in a project
Create new project items from issues/PRs
Update project item field values

Issue Management

Create new issues with automatic type detection and labeling
Smart detection of issue types: Epic, Feature, Bug, Task, Story, Documentation
Create parent-child relationships between issues (Epic > Feature > Story/Task)
Update existing issues (title, body, state, labels, assignees, milestone)
List issues with filtering options (state, labels, assignee)
Get detailed issue information including comments and project associations
View complete issue hierarchy (parents and children)
Ensure standard issue type labels exist in repositories

Setup

Clone this repository
Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```
Configure your GitHub token in Claude Desktop settings (see Integration section below)

Usage

Running the server

The server is designed to be run through Claude Desktop's MCP integration.

For local development with a .env file:

npm run dev

Note: The production server (npm start) requires the GITHUB_TOKEN environment variable to be set externally.

Available Tools

Project Tools

create_project

Create a new GitHub project.

Parameters:

owner (required): Repository owner or organization name
title (required): Project title
repo (optional): Repository name (omit for organization project)

list_projects

List GitHub projects for a repository or organization.

Parameters:

owner (required): Repository owner or organization name
repo (optional): Repository name (omit for organization projects)
projectsType (optional): "repository" or "organization" (default: "repository")

get_project

Get detailed information about a specific project.

Parameters:

projectNumber (required): Project number
owner (required): Repository owner or organization name
repo (optional): Repository name (omit for organization projects)

list_project_items

List items in a GitHub project.

Parameters:

projectId (required): Project node ID
first (optional): Number of items to return (default: 20)

create_project_item

Add an existing issue or pull request to a project.

Parameters:

projectId (required): Project node ID
contentId (required): Issue or PR node ID

update_project_item_field

Update a field value for a project item.

Parameters:

projectId (required): Project node ID
itemId (required): Project item node ID
fieldId (required): Field node ID
value (required): New value for the field

Issue Tools

create_issue

Create a new issue in a repository with automatic type detection.

Parameters:

owner (required): Repository owner (automatically converted to lowercase)
repo (required): Repository name
title (required): Issue title
body (optional): Issue body/description
labels (optional): Array of label names to assign
assignees (optional): Array of usernames to assign
milestone (optional): Milestone number to assign
parentIssueNumber (optional): Parent issue number to link this issue to

Automatic Type Detection: The tool analyzes the title and body to automatically add appropriate labels:

Epic: Large initiatives, milestones, parent tasks
Feature: New functionality, enhancements, implementations
Bug: Errors, fixes, crashes, broken functionality
Task: General tasks, chores, refactoring, updates
Story: User stories, "as a user" scenarios
Documentation: Docs, README, guides

update_issue

Update an existing issue.

Parameters:

owner (required): Repository owner
repo (required): Repository name
issueNumber (required): Issue number
title (optional): New title
body (optional): New body
state (optional): "open" or "closed"
labels (optional): Replace all labels with this array
assignees (optional): Replace all assignees with this array
milestone (optional): New milestone number (or null to remove)

list_issues

List issues in a repository.

Parameters:

owner (required): Repository owner
repo (required): Repository name
state (optional): "open", "closed", or "all" (default: "open")
labels (optional): Array of labels to filter by
assignee (optional): Filter by assignee username
first (optional): Number of issues to return (default: 20)

get_issue

Get detailed information about a specific issue.

Parameters:

owner (required): Repository owner
repo (required): Repository name
issueNumber (required): Issue number

ensure_labels

Ensure standard issue type labels exist in the repository.

Parameters:

owner (required): Repository owner
repo (required): Repository name
labels (optional): Array of label definitions with:
- name (required): Label name
- color (required): Hex color without #
- description (optional): Label description

If no labels are provided, creates default issue type labels (epic, feature, bug, task, story, documentation).

link_issues

Create parent-child relationships between issues.

Parameters:

owner (required): Repository owner
repo (required): Repository name
parentIssueNumber (required): Parent issue number (e.g., Epic or Feature)
childIssueNumber (required): Child issue number to link
linkType (optional): Relationship type - "tracks" (default), "blocks", or "related"

set_parent

Set or update the parent of an issue (simpler alternative to link_issues).

Parameters:

owner (required): Repository owner
repo (required): Repository name
issueNumber (required): Issue number to set parent for
parentIssueNumber (required): Parent issue number (e.g., Epic or Feature)

get_issue_hierarchy

Get the complete hierarchy of an issue showing all parents and children.

Parameters:

owner (required): Repository owner
repo (required): Repository name
issueNumber (required): Issue number to get hierarchy for

add_sub_issue

Add a native sub-issue relationship using GitHub beta API (creates parent-child relationship visible in GitHub's UI).

Parameters:

owner (required): Repository owner
repo (required): Repository name
parentIssueNumber (required): Parent issue number
childIssueNumber (required): Child issue number to add as sub-issue

Note: This uses GitHub's beta API. If not available, it falls back to task list approach.

Integration with Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "github-projects": {
      "command": "node",
      "args": ["/path/to/github-projects-mcp/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "your_github_personal_access_token"
      }
    }
  }
}

Required GitHub Token Permissions:

repo - For accessing repository projects
read:org - For accessing organization projects
project - For full project access (read/write)

Create your token at: https://github.com/settings/tokens

Example Usage

Project Examples

Create a new project:

Tool: create_project
Arguments: {
  "owner": "octocat",
  "repo": "hello-world",
  "title": "My New Project"
}

List all projects in a repository:

Tool: list_projects
Arguments: {
  "owner": "octocat",
  "repo": "hello-world"
}

Get project details:

Tool: get_project
Arguments: {
  "owner": "octocat",
  "repo": "hello-world",
  "projectNumber": 1
}

Issue Examples

Ensure issue type labels exist:

Tool: ensure_labels
Arguments: {
  "owner": "octocat",
  "repo": "hello-world"
}

Create a new issue (auto-detects as bug):

Tool: create_issue
Arguments: {
  "owner": "octocat",
  "repo": "hello-world",
  "title": "Bug: Application crashes on startup",
  "body": "When I try to start the application, it crashes with error XYZ.",
  "labels": ["high-priority"],
  "assignees": ["octocat"]
}

Create an epic:

Tool: create_issue
Arguments: {
  "owner": "octocat",
  "repo": "hello-world",
  "title": "Epic: Implement user authentication system",
  "body": "This epic covers the implementation of a complete authentication system including login, registration, and password recovery."
}

Create a feature under an epic:

Tool: create_issue
Arguments: {
  "owner": "octocat",
  "repo": "hello-world",
  "title": "Feature: Implement login functionality",
  "body": "Implement secure login with JWT tokens",
  "parentIssueNumber": 100
}

Link existing issues:

Tool: link_issues
Arguments: {
  "owner": "octocat",
  "repo": "hello-world",
  "parentIssueNumber": 100,
  "childIssueNumber": 101,
  "linkType": "tracks"
}

Set parent for an issue (simpler syntax):

Tool: set_parent
Arguments: {
  "owner": "octocat",
  "repo": "hello-world",
  "issueNumber": 101,
  "parentIssueNumber": 100
}

View issue hierarchy:

Tool: get_issue_hierarchy
Arguments: {
  "owner": "octocat",
  "repo": "hello-world",
  "issueNumber": 100
}

Add native sub-issue relationship (beta):

Tool: add_sub_issue
Arguments: {
  "owner": "octocat",
  "repo": "hello-world",
  "parentIssueNumber": 100,
  "childIssueNumber": 101
}

Update an issue:

Tool: update_issue
Arguments: {
  "owner": "octocat",
  "repo": "hello-world",
  "issueNumber": 42,
  "state": "closed",
  "labels": ["bug", "fixed"]
}

List open issues with a specific label:

Tool: list_issues
Arguments: {
  "owner": "octocat",
  "repo": "hello-world",
  "state": "open",
  "labels": ["bug"]
}

Add an issue to a project:

Tool: create_project_item
Arguments: {
  "projectId": "PVT_kwDOBgKK184AAAAA",
  "contentId": "I_kwDOBgKK185BBBBB"
}

Development

The server is built with:

TypeScript for type safety
@modelcontextprotocol/sdk for MCP server implementation
@octokit/graphql for GitHub GraphQL API access
dotenv for environment configuration

Author

Created by ProRanked

License

MIT License - see LICENSE file for details

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
src		src
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
examples.md		examples.md
package-lock.json		package-lock.json
package.json		package.json
test-example.md		test-example.md
test-mcp-server.js		test-mcp-server.js
test-server.js		test-server.js
tsconfig.json		tsconfig.json

License

ProRanked/github-projects-mcp

Folders and files

Latest commit

History

Repository files navigation

GitHub Projects MCP Server

Features

Project Management

Issue Management

Setup

Usage

Running the server

Available Tools

Project Tools

create_project

list_projects

get_project

list_project_items

create_project_item

update_project_item_field

Issue Tools

create_issue

update_issue

list_issues

get_issue

ensure_labels

link_issues

set_parent

get_issue_hierarchy

add_sub_issue

Integration with Claude Desktop

Required GitHub Token Permissions:

Example Usage

Project Examples

Issue Examples

Development

Author

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Packages