mcp github projects
Enables users to interact with GitHub's Projects v2 API through natural language for Agile project management, supporting repository details, issue tracking, and project board management operations.
Enables users to interact with GitHub's Projects v2 API through natural language for Agile project management, supporting repository details, issue tracking, and project board management operations.
An MCP (Model Context Protocol) server that enables AI agents to create and manage Agile Sprint-based projects using GitHub Projects.
To install GitHub Projects MCP Server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install taylor-lindores-reeves/mcp-github-projects --client claude
Clone this repository:
git clone https://github.com/taylor-lindores-reeves/mcp-github-projects.git
cd mcp-github-projects
Install dependencies:
bun install
Create a .env
file with your GitHub token:
GITHUB_TOKEN=your_github_personal_access_token
GITHUB_OWNER=your_github_username
Build the server:
bun run build
Configure your MCP client with the following settings:
{
"mcpServers": {
"GitHubProjects": {
"command": "bun",
"args": [
"/path/to/your/directory/mcp-github-projects-main/build/index.js"
],
"env": {
"GITHUB_TOKEN": "your_github_personal_access_token",
"GITHUB_OWNER": "your_github_username_or_org"
}
}
}
}
GITHUB_TOKEN
: GitHub Personal Access Token with appropriate permissionsGITHUB_OWNER
: GitHub username or organization nameThis MCP server requires a GitHub Personal Access Token (classic) with the following permissions:
project
- Full control of projectsread:project
- Read access of projectsrepo
- Full control of private repositoriesrepo:status
- Access commit statusrepo_deployment
- Access deployment statuspublic_repo
- Access public repositoriesrepo:invite
- Access repository invitationssecurity_events
- Read and write security eventsbun run build
bun run graphql-codegen
This project is a MCP Server for GitHub's GraphQL API, with focus on Project V2 operations. The codebase provides typed access to GitHub projects functionality through GraphQL.
[
{
"description": "Get a GitHub repository by owner and name",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"owner": {
"description": "Repository owner (username)",
"type": "string"
},
"repo": {
"description": "Repository name",
"type": "string"
}
},
"required": [
"owner",
"repo"
],
"type": "object"
},
"name": "get-repository"
},
{
"description": "List repositories for a user",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"direction": {
"default": "asc",
"description": "Sort direction",
"enum": [
"asc",
"desc"
],
"type": "string"
},
"owner": {
"description": "Username",
"type": "string"
},
"page": {
"default": 1,
"description": "Page number",
"type": "number"
},
"per_page": {
"default": 30,
"description": "Items per page (max 100)",
"type": "number"
},
"sort": {
"default": "full_name",
"description": "Sort field",
"enum": [
"created",
"updated",
"pushed",
"full_name"
],
"type": "string"
},
"type": {
"default": "all",
"description": "Type of repositories to list",
"enum": [
"all",
"owner",
"public",
"private",
"member"
],
"type": "string"
}
},
"required": [
"owner"
],
"type": "object"
},
"name": "list-repositories"
},
{
"description": "Get a GitHub Project by ID",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"projectId": {
"description": "GitHub Project ID",
"type": "string"
}
},
"required": [
"projectId"
],
"type": "object"
},
"name": "get-project"
},
{
"description": "List GitHub Projects for a user",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"after": {
"description": "Cursor for pagination",
"type": "string"
},
"first": {
"description": "Number of projects to return (max 100)",
"type": "number"
},
"owner": {
"description": "GitHub username",
"type": "string"
}
},
"required": [
"owner"
],
"type": "object"
},
"name": "list-projects"
},
{
"description": "Get status columns for a GitHub Project",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"projectId": {
"description": "GitHub Project ID",
"type": "string"
}
},
"required": [
"projectId"
],
"type": "object"
},
"name": "get-project-columns"
},
{
"description": "Get fields for a GitHub Project",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"projectId": {
"description": "GitHub Project ID",
"type": "string"
}
},
"required": [
"projectId"
],
"type": "object"
},
"name": "get-project-fields"
},
{
"description": "Get items (issues) from a GitHub Project",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"after": {
"description": "Cursor for pagination",
"type": "string"
},
"filter": {
"description": "Filter for items (e.g., status field value)",
"type": "string"
},
"first": {
"description": "Number of items to return (max 100)",
"type": "number"
},
"projectId": {
"description": "GitHub Project ID",
"type": "string"
}
},
"required": [
"projectId"
],
"type": "object"
},
"name": "get-project-items"
},
{
"description": "Add an issue or PR to a GitHub Project",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"contentId": {
"description": "ID of the content to add (issue or PR ID)",
"type": "string"
},
"fieldValues": {
"description": "Field values to set for the item",
"items": {
"additionalProperties": false,
"properties": {
"fieldId": {
"description": "ID of the field",
"type": "string"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"additionalProperties": false,
"properties": {
"singleSelectOptionId": {
"description": "ID of the single select option",
"type": "string"
}
},
"required": [
"singleSelectOptionId"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"iterationId": {
"description": "ID of the iteration",
"type": "string"
}
},
"required": [
"iterationId"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"date": {
"description": "ISO date string",
"type": "string"
}
},
"required": [
"date"
],
"type": "object"
}
],
"description": "Value to set for the field"
}
},
"required": [
"fieldId",
"value"
],
"type": "object"
},
"type": "array"
},
"projectId": {
"description": "GitHub Project ID",
"type": "string"
}
},
"required": [
"projectId",
"contentId"
],
"type": "object"
},
"name": "create-project-item"
},
{
"description": "Update a field value for a project item",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"fieldId": {
"description": "ID of the field to update",
"type": "string"
},
"itemId": {
"description": "ID of the project item",
"type": "string"
},
"projectId": {
"description": "GitHub Project ID",
"type": "string"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"additionalProperties": false,
"properties": {
"singleSelectOptionId": {
"description": "ID of the single select option",
"type": "string"
}
},
"required": [
"singleSelectOptionId"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"iterationId": {
"description": "ID of the iteration",
"type": "string"
}
},
"required": [
"iterationId"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"date": {
"description": "ISO date string",
"type": "string"
}
},
"required": [
"date"
],
"type": "object"
}
],
"description": "New value for the field"
}
},
"required": [
"projectId",
"itemId",
"fieldId",
"value"
],
"type": "object"
},
"name": "update-project-item-field"
},
{
"description": "Create a new GitHub Project",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"description": {
"description": "Project description",
"type": "string"
},
"ownerId": {
"description": "Owner ID (user or organization)",
"type": "string"
},
"repositoryId": {
"description": "Repository ID to link the project to",
"type": "string"
},
"title": {
"description": "Project title",
"type": "string"
}
},
"required": [
"ownerId",
"title"
],
"type": "object"
},
"name": "create-project"
},
{
"description": "Update an existing GitHub Project",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"closed": {
"description": "Project closed status",
"type": "boolean"
},
"description": {
"description": "New project description",
"type": "string"
},
"projectId": {
"description": "GitHub Project ID",
"type": "string"
},
"public": {
"description": "Project visibility",
"type": "boolean"
},
"shortDescription": {
"description": "New short description",
"type": "string"
},
"title": {
"description": "New project title",
"type": "string"
}
},
"required": [
"projectId"
],
"type": "object"
},
"name": "update-project"
},
{
"description": "Delete a GitHub Project",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"projectId": {
"description": "GitHub Project ID to delete",
"type": "string"
}
},
"required": [
"projectId"
],
"type": "object"
},
"name": "delete-project"
},
{
"description": "Copy a GitHub Project",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"includeFields": {
"default": true,
"description": "Whether to include fields in the copied project",
"type": "boolean"
},
"includeItems": {
"default": false,
"description": "Whether to include items in the copied project",
"type": "boolean"
},
"ownerId": {
"description": "New owner ID",
"type": "string"
},
"projectId": {
"description": "Source GitHub Project ID to copy",
"type": "string"
},
"title": {
"description": "Title for the new project",
"type": "string"
}
},
"required": [
"projectId",
"ownerId"
],
"type": "object"
},
"name": "copy-project"
},
{
"description": "Add a draft issue to a GitHub Project",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"assigneeIds": {
"description": "IDs of users to assign",
"items": {
"type": "string"
},
"type": "array"
},
"body": {
"description": "Draft issue body",
"type": "string"
},
"projectId": {
"description": "GitHub Project ID",
"type": "string"
},
"title": {
"description": "Draft issue title",
"type": "string"
}
},
"required": [
"projectId",
"title"
],
"type": "object"
},
"name": "add-draft-issue"
},
{
"description": "Convert a draft issue to a regular issue",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"body": {
"description": "Body for the new issue",
"type": "string"
},
"draftIssueId": {
"description": "Draft issue ID to convert",
"type": "string"
},
"projectId": {
"description": "GitHub Project ID",
"type": "string"
},
"repositoryId": {
"description": "Repository ID where to create the issue",
"type": "string"
},
"title": {
"description": "Title for the new issue",
"type": "string"
}
},
"required": [
"projectId",
"draftIssueId",
"repositoryId"
],
"type": "object"
},
"name": "convert-draft-issue"
},
{
"description": "Add an existing issue or PR to a GitHub Project",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"contentId": {
"description": "ID of the content to add (issue or PR ID)",
"type": "string"
},
"projectId": {
"description": "GitHub Project ID",
"type": "string"
}
},
"required": [
"projectId",
"contentId"
],
"type": "object"
},
"name": "add-item-to-project"
},
{
"description": "Update the position of an item in a GitHub Project",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"afterId": {
"description": "ID of the item to position after",
"type": "string"
},
"itemId": {
"description": "ID of the project item to reposition",
"type": "string"
},
"projectId": {
"description": "GitHub Project ID",
"type": "string"
}
},
"required": [
"projectId",
"itemId"
],
"type": "object"
},
"name": "update-item-position"
},
{
"description": "Remove an item from a GitHub Project",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"itemId": {
"description": "ID of the project item to delete",
"type": "string"
},
"projectId": {
"description": "GitHub Project ID",
"type": "string"
}
},
"required": [
"projectId",
"itemId"
],
"type": "object"
},
"name": "delete-project-item"
},
{
"description": "Create a new field in a GitHub Project",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"dataType": {
"description": "Field data type",
"enum": [
"TEXT",
"NUMBER",
"DATE",
"SINGLE_SELECT",
"ITERATION"
],
"type": "string"
},
"name": {
"description": "Field name",
"type": "string"
},
"projectId": {
"description": "GitHub Project ID",
"type": "string"
},
"singleSelectOptions": {
"description": "Options for single select field",
"items": {
"additionalProperties": false,
"properties": {
"color": {
"description": "Option color (e.g., BLUE, GREEN, RED)",
"type": "string"
},
"description": {
"description": "Option description",
"type": "string"
},
"name": {
"description": "Option name",
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"projectId",
"dataType",
"name"
],
"type": "object"
},
"name": "create-project-field"
},
{
"description": "Update a field in a GitHub Project",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"dataType": {
"description": "New field data type",
"enum": [
"TEXT",
"NUMBER",
"DATE",
"SINGLE_SELECT",
"ITERATION"
],
"type": "string"
},
"fieldId": {
"description": "ID of the field to update",
"type": "string"
},
"name": {
"description": "New field name",
"type": "string"
},
"projectId": {
"description": "GitHub Project ID",
"type": "string"
},
"singleSelectOptions": {
"description": "Updated options for single select field",
"items": {
"additionalProperties": false,
"properties": {
"color": {
"description": "New option color",
"type": "string"
},
"description": {
"description": "New option description",
"type": "string"
},
"name": {
"description": "New option name",
"type": "string"
},
"optionId": {
"description": "Option ID to update",
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"required": [
"projectId",
"fieldId"
],
"type": "object"
},
"name": "update-project-field"
},
{
"description": "Delete a field from a GitHub Project",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"fieldId": {
"description": "ID of the field to delete",
"type": "string"
},
"projectId": {
"description": "GitHub Project ID",
"type": "string"
}
},
"required": [
"projectId",
"fieldId"
],
"type": "object"
},
"name": "delete-project-field"
},
{
"description": "Update the status of a GitHub Project",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"projectId": {
"description": "GitHub Project ID",
"type": "string"
},
"text": {
"description": "Status update text",
"type": "string"
},
"updateId": {
"description": "ID of the status update to modify",
"type": "string"
}
},
"required": [
"projectId",
"text"
],
"type": "object"
},
"name": "update-project-status"
},
{
"description": "Archive an item in a GitHub Project",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"itemId": {
"description": "ID of the project item to archive",
"type": "string"
},
"projectId": {
"description": "GitHub Project ID",
"type": "string"
}
},
"required": [
"projectId",
"itemId"
],
"type": "object"
},
"name": "archive-project-item"
},
{
"description": "Unarchive an item in a GitHub Project",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"itemId": {
"description": "ID of the project item to unarchive",
"type": "string"
},
"projectId": {
"description": "GitHub Project ID",
"type": "string"
}
},
"required": [
"projectId",
"itemId"
],
"type": "object"
},
"name": "unarchive-project-item"
},
{
"description": "Clear a field value for an item in a GitHub Project",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"fieldId": {
"description": "ID of the field to clear",
"type": "string"
},
"itemId": {
"description": "ID of the project item",
"type": "string"
},
"projectId": {
"description": "GitHub Project ID",
"type": "string"
}
},
"required": [
"projectId",
"itemId",
"fieldId"
],
"type": "object"
},
"name": "clear-item-field-value"
},
{
"description": "Mark a GitHub Project as a template",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"projectId": {
"description": "GitHub Project ID to mark as template",
"type": "string"
}
},
"required": [
"projectId"
],
"type": "object"
},
"name": "mark-project-as-template"
},
{
"description": "Unmark a GitHub Project as a template",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"projectId": {
"description": "GitHub Project ID to unmark as template",
"type": "string"
}
},
"required": [
"projectId"
],
"type": "object"
},
"name": "unmark-project-as-template"
},
{
"description": "Get a GitHub issue by number",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"issueNumber": {
"description": "Issue number",
"type": "number"
},
"owner": {
"description": "Repository owner (username)",
"type": "string"
},
"repo": {
"description": "Repository name",
"type": "string"
}
},
"required": [
"owner",
"repo",
"issueNumber"
],
"type": "object"
},
"name": "get-issue"
},
{
"description": "List issues for a repository",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"assignee": {
"description": "Filter by assignee username",
"type": "string"
},
"direction": {
"default": "desc",
"description": "Sort direction",
"enum": [
"asc",
"desc"
],
"type": "string"
},
"labels": {
"description": "Filter by labels",
"items": {
"type": "string"
},
"type": "array"
},
"milestone": {
"description": "Filter by milestone number or '*'",
"type": "string"
},
"owner": {
"description": "Repository owner (username)",
"type": "string"
},
"page": {
"default": 1,
"description": "Page number",
"type": "number"
},
"per_page": {
"default": 30,
"description": "Items per page (max 100)",
"type": "number"
},
"repo": {
"description": "Repository name",
"type": "string"
},
"sort": {
"default": "created",
"description": "Sort field",
"enum": [
"created",
"updated",
"comments"
],
"type": "string"
},
"state": {
"default": "open",
"description": "Issue state (open, closed, all)",
"enum": [
"open",
"closed",
"all"
],
"type": "string"
}
},
"required": [
"owner",
"repo"
],
"type": "object"
},
"name": "list-issues"
},
{
"description": "Create a new GitHub issue",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"assignees": {
"description": "Usernames to assign",
"items": {
"type": "string"
},
"type": "array"
},
"body": {
"description": "Issue body/description",
"type": "string"
},
"labels": {
"description": "Labels to apply",
"items": {
"type": "string"
},
"type": "array"
},
"milestone": {
"description": "Milestone ID",
"type": "number"
},
"owner": {
"description": "Repository owner (username)",
"type": "string"
},
"repo": {
"description": "Repository name",
"type": "string"
},
"title": {
"description": "Issue title",
"type": "string"
}
},
"required": [
"owner",
"repo",
"title"
],
"type": "object"
},
"name": "create-issue"
},
{
"description": "Update an existing GitHub issue",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"assignees": {
"description": "Usernames to assign (replaces existing)",
"items": {
"type": "string"
},
"type": "array"
},
"body": {
"description": "New body",
"type": "string"
},
"issueNumber": {
"description": "Issue number",
"type": "number"
},
"labels": {
"description": "Labels to apply (replaces existing)",
"items": {
"type": "string"
},
"type": "array"
},
"milestone": {
"description": "Milestone ID (null to clear)",
"type": [
"number",
"null"
]
},
"owner": {
"description": "Repository owner (username)",
"type": "string"
},
"repo": {
"description": "Repository name",
"type": "string"
},
"state": {
"description": "State (open or closed)",
"enum": [
"open",
"closed"
],
"type": "string"
},
"title": {
"description": "New title",
"type": "string"
}
},
"required": [
"owner",
"repo",
"issueNumber"
],
"type": "object"
},
"name": "update-issue"
}
]