Github Project Manager
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Integrations
Supports loading environment configuration from .env files, used to store GitHub tokens and other configuration settings.
Allows management of GitHub issues, pull requests, and projects. Features include creating, updating, and listing issues; adding comments; creating, updating, and merging pull requests; managing pull request reviews; and creating and managing GitHub projects.
MCP GitHub Project Manager
A Model Context Protocol (MCP) implementation for managing GitHub issues and projects.
Features
GitHub Issue Management
- Create issues
- Update issues
- List issues with filtering options
- Get issue details
- Add comments to issues
- Close issues
GitHub Pull Request Management
- Create pull requests
- Update pull requests
- List pull requests with filtering options
- Get pull request details
- Merge pull requests
- Check if a pull request has been merged
- Create and manage pull request reviews
- Add and list review comments
- Request and remove reviewers
- Update pull request branches
GitHub Project Management
- Create projects
- Add issues to projects
- Update project items (move between columns)
- List project items
Installation
Build Process
When you build the project with npm run build
, the following happens:
- The TypeScript code is compiled to JavaScript in the
dist
folder - The
.env
file (if it exists) is automatically copied to thedist
folder - If no
.env
file exists, the.env.example
file is copied to thedist
folder as a template
This ensures that your environment configuration is always available when running the compiled code, making deployment easier.
Usage
Environment Setup
Before using the GitHub Project Manager, you need to set up a GitHub token:
Using npm Scripts (Recommended)
The easiest way to set up your environment is to use the provided npm scripts:
This interactive script will prompt you for your GitHub Personal Access Token and create a properly formatted .env
file. When you build the project with npm run build
, this file will be automatically copied to the dist
folder.
Using Environment File Manually
You can also manually create an environment file. Create a .env
file in the root directory of your project based on the provided .env.example
:
Your .env
file should contain at least:
When you build the project with npm run build
, the .env
file will be automatically copied to the dist
folder, making it available when running the compiled code.
Using Environment Variables
You can also set the GitHub token as an environment variable:
Running the Server
There are several ways to run the GitHub Project Manager server:
Using the Shell Script
The easiest way to run the server is to use the provided shell script:
This script will automatically look for the .env
file in both the dist
folder and the project root, and load the environment variables before starting the server.
Using Node.js
You can also run the server directly using Node.js:
The server will automatically look for the .env
file in the appropriate locations.
Using the API
Available Tools
Issue Management
create_issue
Create a new issue in a GitHub repository.
Parameters:
owner
(string): Repository owner (username or organization)repo
(string): Repository nametitle
(string): Issue titlebody
(string, optional): Issue body/descriptionlabels
(string[], optional): Labels to add to this issueassignees
(string[], optional): GitHub usernames to assign to this issuemilestone
(number, optional): Milestone number to associate with this issue
update_issue
Update an existing issue in a GitHub repository.
Parameters:
owner
(string): Repository owner (username or organization)repo
(string): Repository nameissue_number
(number): Issue numbertitle
(string, optional): New issue titlebody
(string, optional): New issue bodystate
(string, optional): New issue state ('open' or 'closed')labels
(string[], optional): Labels to setassignees
(string[], optional): GitHub usernames to assignmilestone
(number, optional): Milestone to set
list_issues
List issues in a GitHub repository with filtering options.
Parameters:
owner
(string): Repository owner (username or organization)repo
(string): Repository namestate
(string, optional): Issue state ('open', 'closed', or 'all')sort
(string, optional): Sort field ('created', 'updated', or 'comments')direction
(string, optional): Sort direction ('asc' or 'desc')since
(string, optional): Filter by updated date (ISO 8601 format)per_page
(number, optional): Results per pagepage
(number, optional): Page numberlabels
(string[], optional): Filter by labelsassignee
(string, optional): Filter by assigneecreator
(string, optional): Filter by creatormentioned
(string, optional): Filter by mentioned usermilestone
(string, optional): Filter by milestone number or title
get_issue
Get details of a specific issue in a GitHub repository.
Parameters:
owner
(string): Repository owner (username or organization)repo
(string): Repository nameissue_number
(number): Issue number
add_issue_comment
Add a comment to an existing issue.
Parameters:
owner
(string): Repository owner (username or organization)repo
(string): Repository nameissue_number
(number): Issue numberbody
(string): Comment text
Pull Request Management
create_pull_request
Create a new pull request in a GitHub repository.
Parameters:
owner
(string): Repository owner (username or organization)repo
(string): Repository nametitle
(string): Pull request titlebody
(string, optional): Pull request body/descriptionhead
(string): The name of the branch where your changes are implementedbase
(string): The name of the branch you want the changes pulled intodraft
(boolean, optional): Whether to create the pull request as a draftmaintainer_can_modify
(boolean, optional): Whether maintainers can modify the pull request
update_pull_request
Update an existing pull request in a GitHub repository.
Parameters:
owner
(string): Repository owner (username or organization)repo
(string): Repository namepull_number
(number): Pull request numbertitle
(string, optional): New pull request titlebody
(string, optional): New pull request bodystate
(string, optional): New pull request state ('open' or 'closed')base
(string, optional): The name of the branch you want the changes pulled intomaintainer_can_modify
(boolean, optional): Whether maintainers can modify the pull request
list_pull_requests
List pull requests in a GitHub repository with filtering options.
Parameters:
owner
(string): Repository owner (username or organization)repo
(string): Repository namestate
(string, optional): Pull request state ('open', 'closed', or 'all')head
(string, optional): Filter by head branchbase
(string, optional): Filter by base branchsort
(string, optional): Sort field ('created', 'updated', 'popularity', or 'long-running')direction
(string, optional): Sort direction ('asc' or 'desc')per_page
(number, optional): Results per pagepage
(number, optional): Page number
get_pull_request
Get details of a specific pull request in a GitHub repository.
Parameters:
owner
(string): Repository owner (username or organization)repo
(string): Repository namepull_number
(number): Pull request number
merge_pull_request
Merge a pull request.
Parameters:
owner
(string): Repository owner (username or organization)repo
(string): Repository namepull_number
(number): Pull request numbercommit_title
(string, optional): Title for the automatic commit messagecommit_message
(string, optional): Extra detail to append to automatic commit messagemerge_method
(string, optional): Merge method to use ('merge', 'squash', or 'rebase')
is_pull_request_merged
Check if a pull request has been merged.
Parameters:
owner
(string): Repository owner (username or organization)repo
(string): Repository namepull_number
(number): Pull request number
create_pull_request_review
Create a review for a pull request.
Parameters:
owner
(string): Repository owner (username or organization)repo
(string): Repository namepull_number
(number): Pull request numberbody
(string, optional): The body text of the reviewevent
(string, optional): The review action to perform ('APPROVE', 'REQUEST_CHANGES', or 'COMMENT')comments
(array, optional): Comments to post as part of the review, each with:path
(string): The relative path to the file being commented onposition
(number): The position in the diff where the comment should be placedbody
(string): The text of the comment
list_pull_request_reviews
List reviews for a pull request.
Parameters:
owner
(string): Repository owner (username or organization)repo
(string): Repository namepull_number
(number): Pull request numberper_page
(number, optional): Results per pagepage
(number, optional): Page number
create_pull_request_review_comment
Create a review comment for a pull request.
Parameters:
owner
(string): Repository owner (username or organization)repo
(string): Repository namepull_number
(number): Pull request numberbody
(string): The text of the review commentcommit_id
(string, optional): The SHA of the commit to comment onpath
(string, optional): The relative path to the file being commented onposition
(number, optional): The position in the diff where the comment should be placedin_reply_to
(number, optional): The comment ID to reply to
list_pull_request_review_comments
List review comments for a pull request.
Parameters:
owner
(string): Repository owner (username or organization)repo
(string): Repository namepull_number
(number): Pull request numbersort
(string, optional): Sort field ('created' or 'updated')direction
(string, optional): Sort direction ('asc' or 'desc')since
(string, optional): Only comments updated at or after this time are returnedper_page
(number, optional): Results per pagepage
(number, optional): Page number
request_reviewers
Request reviewers for a pull request.
Parameters:
owner
(string): Repository owner (username or organization)repo
(string): Repository namepull_number
(number): Pull request numberreviewers
(string[], optional): Usernames of people to request a review fromteam_reviewers
(string[], optional): Names of teams to request a review from
remove_requested_reviewers
Remove requested reviewers from a pull request.
Parameters:
owner
(string): Repository owner (username or organization)repo
(string): Repository namepull_number
(number): Pull request numberreviewers
(string[]): Usernames of people to remove from the review requestteam_reviewers
(string[], optional): Names of teams to remove from the review request
update_pull_request_branch
Update a pull request branch with the latest upstream changes.
Parameters:
owner
(string): Repository owner (username or organization)repo
(string): Repository namepull_number
(number): Pull request numberexpected_head_sha
(string, optional): The expected SHA of the pull request head
Project Management
create_project
Create a new GitHub project board.
Parameters:
owner
(string): Organization name or usernamename
(string): Project namebody
(string, optional): Project description
add_project_item
Add an issue or pull request to a GitHub project.
Parameters:
project_id
(number): Project IDcontent_id
(number): Issue or PR IDcontent_type
(string): Type of content to add ('Issue' or 'PullRequest')
update_project_item
Move an item between columns in a GitHub project.
Parameters:
project_id
(number): Project IDitem_id
(number): Card ID to movecolumn_id
(number): Column ID to move the card toposition
(string or number, optional): Position in the column ('top', 'bottom', or specific position)
list_project_items
List items in a GitHub project.
Parameters:
project_id
(number): Project IDcolumn_id
(number, optional): Column ID to filter by
Error Handling
The GitHub Project Manager provides detailed error information for various scenarios:
- Authentication errors
- Resource not found errors
- Validation errors
- Rate limit errors
- Network errors
Troubleshooting
Environment Configuration Issues
If you encounter issues with the environment configuration:
- Missing GitHub Token: If you see an error about a missing GitHub token, make sure you've created a
.env
file with yourGITHUB_PERSONAL_TOKEN
using one of the methods described above. - Environment File Not Found: If the server can't find your
.env
file, try runningnpm run generate-env
to create one, or manually copy.env.example
to.env
and add your token. - Token Permissions: Ensure your GitHub token has the necessary permissions for the operations you're trying to perform (repo, project, etc.).
- Build Issues: If you've modified the environment configuration, make sure to rebuild the project with
npm run build
to copy the updated.env
file to thedist
folder.
License
MIT
You must be authenticated.
Allow to manage Issues and Project on Github
- Features
- Installation
- Build Process
- Usage
- Available Tools
- Error Handling
- Troubleshooting
- License