Setting the file. One moment.
Subchapter 193.7
references/projects.mdMarkdown8 KBView on GitHub
GitHub Projects V2 is managed via GraphQL. The MCP server provides three tools that wrap the GraphQL API, so you typically don’t need raw GraphQL.
List projects:
Call mcp__github__projects_list with method: "list_projects", owner, and owner_type (“user” or “organization”).
List project fields:
Call mcp__github__projects_list with method: "list_project_fields" and project_number.
List project items:
Call mcp__github__projects_list with method: "list_project_items" and project_number.
Add an issue/PR to a project:
Call mcp__github__projects_write with method: "add_project_item", project_id (node ID), and content_id (issue/PR node ID).
Update a project item field value:
Call mcp__github__projects_write with method: "update_project_item", project_id, item_id, field_id, and value (object with one of: text, number, date, singleSelectOptionId, iterationId).
Delete a project item:
Call mcp__github__projects_write with method: "delete_project_item", project_id, and item_id.
projects_list with list_project_fields to get field IDs and option IDsprojects_list with list_project_items to get item IDsprojects_write to add, update, or delete items⚠️ Known issue:
projectsV2(query: "…")does keyword search, not exact name match, and returns results sorted by recency. Common words like “issue” or “bug” return hundreds of false positives. The actual project may be buried dozens of pages deep.
Use this priority order:
gh api graphql -f query='{
organization(login: "ORG") {
projectV2(number: 42) { id title }
}
}' --jq '.data.organization.projectV2'If the user mentions an issue, epic, or milestone that’s in the project, query that issue’s projectItems to discover the project:
gh api graphql -f query='{
repository(owner: "OWNER", name: "REPO") {
issue(number: 123) {
projectItems(first: 10) {
nodes {
id
project { number title id }
}
}
}
}
}' --jq '.data.repository.issue.projectItems.nodes[] | {number: .project.number, title: .project.title, id: .project.id}'This is the most reliable approach for large orgs where name search fails.
Query a large page and filter client-side for an exact title match:
gh api graphql -f query='{
organization(login: "ORG") {
projectsV2(first: 100, query: "search term") {
nodes { number title id }
}
}
}' --jq '.data.organization.projectsV2.nodes[] | select(.title | test("(?i)^exact name$"))'If this returns nothing, paginate with after cursor or broaden the regex. Results are sorted by recency so older projects require pagination.
Call mcp__github__projects_list with method: "list_projects". This works well for orgs with <50 projects but has no name filter, so you must scan all results.
When a user asks for a progress update on a project (e.g., “Give me a progress update for Project X”), follow this workflow:
Find the project — use the finding a project strategies above. Ask the user for a known issue number if name search fails.
Discover fields - call projects_list with list_project_fields to find the Status field (its options tell you the workflow stages) and any Iteration field (to scope to the current sprint).
Get all items - call projects_list with list_project_items. For large projects (100+ items), paginate through all pages. Each item includes its field values (status, iteration, assignees).
Build the report - group items by Status field value and count them. For iteration-based projects, filter to the current iteration first. Present a breakdown like:
Project: Issue Fields (Iteration 42, Mar 2-8)
15 actionable items:
🎉 Done: 4 (27%)
In Review: 3
In Progress: 3
Ready: 2
Blocked: 2Add context - if items have sub-issues, include subIssuesSummary counts. If items have dependencies, note blocked items and what blocks them.
| Operation | Required scope |
|---|---|
| Read projects, fields, items | read:project |
| Add/update/delete items, change field values | project |
Common pitfall: The default gh auth token often only has read:project. Mutations will fail with INSUFFICIENT_SCOPES. To add the write scope:
gh auth refresh -h github.com -s projectThis triggers a browser-based OAuth flow. You must complete it before mutations will work.
When you know the issue but need its project item ID (e.g., to update its Status), query from the issue side:
gh api graphql -f query='
{
repository(owner: "OWNER", name: "REPO") {
issue(number: 123) {
projectItems(first: 5) {
nodes {
id
project { title number }
fieldValues(first: 10) {
nodes {
... on ProjectV2ItemFieldSingleSelectValue {
name
field { ... on ProjectV2SingleSelectField { name } }
}
}
}
}
}
}
}
}' --jq '.data.repository.issue.projectItems.nodes'This returns the item ID, project info, and current field values in one query.
Use gh api graphql to run GraphQL queries and mutations. This is more reliable than MCP tools for write operations.
Find a project and its Status field options:
gh api graphql -f query='
{
organization(login: "ORG") {
projectV2(number: 5) {
id
title
field(name: "Status") {
... on ProjectV2SingleSelectField {
id
options { id name }
}
}
}
}
}' --jq '.data.organization.projectV2'List all fields (including iterations):
gh api graphql -f query='
{
node(id: "PROJECT_ID") {
... on ProjectV2 {
fields(first: 20) {
nodes {
... on ProjectV2Field { id name }
... on ProjectV2SingleSelectField { id name options { id name } }
... on ProjectV2IterationField { id name configuration { iterations { id startDate } } }
}
}
}
}
}' --jq '.data.node.fields.nodes'Update a field value (e.g., set Status to “In Progress”):
gh api graphql -f query='
mutation {
updateProjectV2ItemFieldValue(input: {
projectId: "PROJECT_ID"
itemId: "ITEM_ID"
fieldId: "FIELD_ID"
value: { singleSelectOptionId: "OPTION_ID" }
}) {
projectV2Item { id }
}
}'Value accepts one of: text, number, date, singleSelectOptionId, iterationId.
Add an item:
gh api graphql -f query='
mutation {
addProjectV2ItemById(input: {
projectId: "PROJECT_ID"
contentId: "ISSUE_OR_PR_NODE_ID"
}) {
item { id }
}
}'Delete an item:
gh api graphql -f query='
mutation {
deleteProjectV2Item(input: {
projectId: "PROJECT_ID"
itemId: "ITEM_ID"
}) {
deletedItemId
}
}'# 1. Get the issue's project item ID, project ID, and current status
gh api graphql -f query='{
repository(owner: "github", name: "planning-tracking") {
issue(number: 2574) {
projectItems(first: 1) {
nodes { id project { id title } }
}
}
}
}' --jq '.data.repository.issue.projectItems.nodes[0]'
# 2. Get the Status field ID and "In Progress" option ID
gh api graphql -f query='{
node(id: "PROJECT_ID") {
... on ProjectV2 {
field(name: "Status") {
... on ProjectV2SingleSelectField { id options { id name } }
}
}
}
}' --jq '.data.node.field'
# 3. Update the status
gh api graphql -f query='mutation {
updateProjectV2ItemFieldValue(input: {
projectId: "PROJECT_ID"
itemId: "ITEM_ID"
fieldId: "FIELD_ID"
value: { singleSelectOptionId: "IN_PROGRESS_OPTION_ID" }
}) { projectV2Item { id } }
}'