github / github/github-mcp-server
Feature Request: Expose GitHub Project Item History/Timeline Events
- Dominant language
- Go
- Stars
- 33k
- Forks
- 5k
- Avg merge
- 2d 1h
- Merged PRs (30d)
- 52
Description
## Problem Statement
Currently, the GitHub MCP server provides tools to view the current state of GitHub Project items (issues/PRs in projects), but there's no way to access the historical data about when items moved between columns or how long they spent in each status.
This limits the ability to:
- Track cycle time metrics (time from "In Progress" to "Done")
- Understand bottlenecks in workflows
- Generate velocity and throughput reports
- Analyze team performance over time
## Use Case
As a user working with GitHub Projects, I want to be able to ask questions like:
- "How long did issue #14560 spend in each column of the Move project board?"
- "What's the average time issues spend in 'Review/QA' status?"
- "Show me the timeline of when this issue moved between statuses"
## Current Behavior
The `get_project_item` and `list_project_items` tools only return the current state of items, including their current field values. There's no historical tracking exposed through the MCP server.
## Proposed Solution
Add new tool(s) to expose GitHub Project item timeline/history events. This could be:
### Option 1: New dedicated tool
```typescript
get_project_item_history({
owner: string,
owner_type: 'user' | 'org',
project_number: number,
item_id: number
})
```
Returns an array of events showing when the item was:
- Added to the project
- Moved between columns/status values
- Field values were changed
- Removed from the project (if applicable)
Each event should include:
- Timestamp
- Field that changed (e.g., "Status")
- Previous value
- New value
- Actor (who made the change)
### Option 2: Enhance existing tools
Add an optional `include_history` parameter to `get_project_item` that when set to `true`, includes the historical events alongside the current state.
## GitHub API Support
GitHub's ProjectV2 API supports querying project item events through GraphQL. Example query:
```graphql
query {
node(id: "ITEM_NODE_ID") {
... on ProjectV2Item {
fieldValueByName(name: "Status") {
... on ProjectV2ItemFieldSingleSelectValue {
name
updatedAt
}
}
}
}
}
```
Additionally, the REST API's timeline events endpoint could be used for issue/PR specific events.
## Benefits
- Enables workflow analytics and metrics tracking
- Provides transparency into project management processes
- Allows LLMs to answer time-based questions about project items
- Supports building reports and dashboards through AI
## Additional Context
This feature request came from a real-world scenario where a user wanted to track how long an issue spent in each column of their project board, but the current MCP server tools couldn't provide this information.
Related GitHub API documentation:
- [ProjectV2 API](https://docs.github.com/en/graphql/reference/objects#projectv2item)
- [Issue Timeline Events](https://docs.github.com/en/rest/issues/timeline)
Contributor guide
Assessment
This issue has not been assessed yet.