git-gogo MCP Server

GitHub workflow automation MCP server with project management integration

A Model Context Protocol (MCP) server that streamlines GitHub project workflows by integrating issue management, project boards, and git operations into a conversational AI interface.

Features

• 🎯 Project Management - Show tasks, start issues, track progress
• 📝 Issue Management - Create, list, and manage GitHub issues
• 🏷️ Milestone Management - Create and manage project milestones
• 💬 Discussion Management - Create and manage GitHub discussions with category support
• 🔄 Workflow Automation - Automated commit messages with issue linking
• 📊 Project Board Integration - Update issue status across project boards
• ⚙️ Configuration Management - Persistent project and discussion settings

Prerequisites

• Node.js >= 18.0.0
• GitHub CLI (gh) >= 2.0.0

  # macOS
  brew install gh
    
  # Other platforms: https://cli.github.com/

• GitHub Authentication

  gh auth login
  gh auth refresh -s project  # Required for project board access

Installation

👥 Team Members: See SETUP.md for a quick setup guide!

As MCP Server

1. Install the package:

   npm install -g @purpledotstudio/git-gogo-mcp

2. Add to your MCP configuration:

   File: ~/.codeium/windsurf/mcp_config.json

   {
     "mcpServers": {
       "git-gogo": {
         "command": "git-gogo-mcp"
       }
     }
   }

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

   {
     "mcpServers": {
       "git-gogo": {
         "command": "git-gogo-mcp"
       }
     }
   }

   Option 1: Using CLI (Recommended)

   claude mcp add git-gogo "npx -y @purpledotstudio/git-gogo-mcp"

   Option 2: Manual Configuration

   File (macOS/Linux): ~/.claude/mcp_config.json
   File (Windows): %USERPROFILE%\.claude\mcp_config.json

   {
     "mcpServers": {
       "git-gogo": {
         "command": "git-gogo-mcp"
       }
     }
   }

   File: ~/.trae/mcp_config.json

   {
     "mcpServers": {
       "git-gogo": {
         "command": "git-gogo-mcp"
       }
     }
   }

3. Restart your AI client

Available Tools

Quick Reference

| Tool | Description | Key Parameters | |------|-------------|----------------| | Workflow | | | | show_my_work | Show tasks in 'Ready' status assigned to you | None | | start_issue | Start work on an issue, move to 'In Progress' | issue_number | | commit_changes | Commit with auto-generated message & issue link | files, message?, type? | | Issues | | | | get_my_issues | List issues assigned to you | repo?, state?, limit? | | create_issue_from_todo | Create issue from TODO, add to project | title, body, repo, assignee, projectOwner, projectNumber | | Milestones | | | | get_milestones | List repository milestones | repo, state? | | create_milestone | Create a new milestone | repo, title, description?, due_on? | | Discussions | | | | configure_discussion_categories | Fetch and store discussion categories | repo | | get_discussion_categories | View configured discussion categories | None | | create_discussion | Create a new discussion | repo, title, body, category? | | add_discussion_to_issue | Link a discussion to an issue | repo, issue_number, discussion_url | | Configuration | | | | configure_project | Set default project settings | owner, number, repo, assignee, projectId? | | get_project_config | View current project configuration | None |

Workflow Tools

show_my_work

Show tasks assigned to you in 'Ready' status from the configured project.

Requirements:

• ⚠️ Project must be configured: Use configure_project first if not set up
• Looks for tasks with Status = "Ready"
• Filters by assignee from configured project

What it returns:

• Numbered list of ready tasks
• Issue number, title, labels, milestone, URL
• Prompt to select which task to work on

Usage:

"Show my work"
"What tasks are ready for me?"

Note: If no tasks found, check:

• Tasks exist in project with "Ready" status
• Tasks are assigned to you
• Project configuration is correct (get_project_config)

start_issue

Start working on a GitHub issue by fetching details, moving to 'In Progress', and loading context.

Parameters:

• issue_number (required): Issue number to start working on

What it does:

1. Fetches issue details using gh issue view
2. Finds the issue in the configured project
3. Updates project status to "In Progress"
4. Saves issue to currentIssue in config (for commit_changes)
5. Returns formatted issue details with title, description, labels, milestone, comments

Requirements:

• ⚠️ Project must be configured: Use configure_project first
• Issue must exist in the repository
• Project must have "Status" field with "In Progress" option

Usage:

"Start issue 42"
"Begin work on issue #15"

Typical workflow:

1. show_my_work → See ready tasks
2. start_issue 42 → Begin working on issue #42
3. Make code changes
4. commit_changes → Commit with auto-generated message

commit_changes

Commit changes with auto-generated conventional commit message linked to current issue.

Parameters:

• files (required): Array of modified file paths
• message (optional): Custom commit message. If not provided, will be auto-generated from issue title
• type (optional): Commit type - feat, fix, chore, docs, style, refactor, test, perf. Default: feat

Important Notes:

• ⚠️ Requires active issue: Must call start_issue first to set the current issue
• Automatically adds Closes #<issue_number> to commit message
• Stages specified files with git add
• Clears current issue after successful commit
• Uses conventional commit format: type: message

Auto-generated commit message format:

<type>: <issue title in lowercase>

Closes #<issue_number>

Usage:

"Commit these changes"
"Create a commit for the current issue"
"Commit with type fix"

Example: If current issue is #42 "Add User Authentication":

• Without custom message: feat: add user authentication\n\nCloses #42
• With custom message: <your message>\n\nCloses #42

Issue Management

get_my_issues

Get GitHub issues assigned to you using the GitHub CLI.

Parameters:

• repo (optional): Repository in format 'owner/repo'. If not provided, uses current directory's repository
• state (optional): Filter by state - open, closed, or all (default: open)
• limit (optional): Maximum number of issues to return (default: 30)

Requirements:

• GitHub CLI (gh) must be installed and authenticated
• Repository access (if repo parameter specified)

Returns:

• Formatted list with issue number, title, state, labels, created/updated dates, URL
• Empty message if no issues found

Usage:

"Show my GitHub issues"
"Get my open issues from owner/repo"
"List all my closed issues"

create_issue_from_todo

Create a GitHub issue from a TODO comment and add to project board.

Parameters:

• title (required): Issue title (extracted from TODO)
• body (required): Issue description with context
• repo (required): Repository in format 'owner/repo'
• assignee (required): GitHub username to assign the issue to
• projectOwner (required): Project owner (org or user)
• projectNumber (required): Project number (e.g., 1)
• milestone (optional): Milestone title to add the issue to
• statusValue (optional): Status to set (e.g., 'Backlog', 'Ready', 'In progress'). Default: Backlog
• statusFieldId (optional): Field ID for status. Auto-detected if not provided
• filePath (optional): Absolute path to file containing the TODO comment
• todoComment (optional): Exact TODO comment text to replace (including comment markers like // or #)
• conversationContext (optional): Additional context from conversation (added to issue body under "Discussion Context")

Requirements:

• ⚠️ GitHub CLI with project scope: Run gh auth refresh -s project
• ⚠️ Get milestones first: Use get_milestones to fetch available milestones, then let user select one (or create with create_milestone)

TODO Comment Examples:

// TODO: Add user authentication to this endpoint
// Need to implement JWT token validation and role-based access control

// TODO: Refactor this function to use async/await
// Current callback-based approach is hard to maintain

// FIXME: Memory leak in event listener cleanup
// Event listeners are not being properly removed on component unmount

# TODO: Implement caching for database queries
# This query runs on every request and is slowing down the API

# TODO: Add input validation
# Need to validate email format and password strength

# FIXME: Race condition in concurrent requests
# Multiple simultaneous requests can cause data corruption

// TODO: Add TypeScript types for API responses
// Currently using 'any' which defeats the purpose of TypeScript

// TODO: Implement error boundary for this component
// Uncaught errors crash the entire application

Usage:

"Create an issue from this TODO comment"
"Convert this TODO to a GitHub issue and add it to the project"

The tool will:

1. Extract the TODO comment and context
2. Create a GitHub issue with the TODO as the title
3. Add surrounding code context to the issue body
4. Assign to specified user
5. Add to project board with chosen status
6. Optionally replace the TODO comment with a link to the created issue

Milestone Management

get_milestones

Get list of milestones for a repository.

Parameters:

• repo (required): Repository in format 'owner/repo'
• state (optional): Filter by state - open, closed, or all (default: open)

Returns:

• List of milestones with title, state, description, due date, open/closed issue counts

Usage:

"Get milestones for owner/repo"
"Show all milestones including closed ones"

Note: Call this before create_issue_from_todo to let user select appropriate milestone.

create_milestone

Create a new milestone in a repository.

Parameters:

• repo (required): Repository in format 'owner/repo'
• title (required): Milestone title
• description (optional): Milestone description
• due_on (optional): Due date in ISO 8601 format (YYYY-MM-DD)

Returns:

• Created milestone details with number, title, URL

Usage:

"Create milestone 'Sprint 1' for owner/repo"
"Create milestone with due date 2025-12-31"

Discussion Management

configure_discussion_categories

Fetch and store discussion categories for a repository.

Parameters:

• repo (required): Repository in format 'owner/repo'

What it does:

1. Fetches all available discussion categories from the repository using GitHub GraphQL API
2. Stores category IDs, names, descriptions, and emojis in config.json
3. Saves repository ID for efficient discussion creation

Requirements:

• GitHub CLI (gh) must be installed and authenticated
• Discussions must be enabled for the repository
• Repository access required

Returns:

• List of available categories with names, descriptions, emojis, and IDs

Usage:

"Configure discussion categories for owner/repo"
"Fetch discussion categories"

Note: Run this once per repository before creating discussions. Categories are stored in config for reuse.

get_discussion_categories

View the configured discussion categories.

Returns:

• List of stored discussion categories with names, descriptions, emojis, and IDs
• Repository name for which categories are configured

Usage:

"Show discussion categories"
"What discussion categories are available?"

Note: If no categories are configured, prompts to use configure_discussion_categories first.

create_discussion

Create a new GitHub discussion in a repository. This tool automatically asks the user to select a category.

Parameters:

• repo (required): Repository in format 'owner/repo'
• title (required): Discussion title
• body (required): Discussion body/content (supports Markdown)
• category (optional): Category name or number. If not provided, the tool will show available categories and ask the user to select one

What it does:

1. Automatically fetches and stores discussion categories if not already configured
2. Shows available categories to the user with emojis and descriptions
3. Asks user to select a category by name or number
4. Creates the discussion once category is selected

Requirements:

• GitHub CLI with authentication
• Discussions enabled for repository
• Permission to create discussions

Returns:

• Discussion number, title, category, and URL

Usage:

"Create a discussion called 'Hello World'"
"Start a new discussion about feature requests"

Example Workflow:

User: "Create a discussion called 'Feature Ideas'"
AI: [Calls create_discussion, shows categories]
   
   Select a category for your discussion
   
   Title: Feature Ideas
   
   Available Categories:
   1. 📣 Announcements - Updates from maintainers
   2. 💬 General - Chat about anything and everything here
   3. 💡 Ideas - Share ideas for new features
   4. 🙏 Q&A - Ask the community for help
   
   Please reply with the category name or number (1-4)

User: "Ideas" or "3"
AI: [Creates discussion in Ideas category]
   ✅ Discussion created successfully!
   Title: Feature Ideas
   Number: #42
   Category: 💡 Ideas
   URL: https://github.com/...

Advanced Usage: You can also provide the category directly to skip the selection step:

"Create a discussion called 'Bug Report' in the General category"

add_discussion_to_issue

Add a discussion link to an issue by updating the issue's body. The discussion link will be added at the top of the issue body as a blockquote.

Parameters:

• repo (required): Repository in format 'owner/repo'
• issue_number (required): Issue number to update
• discussion_url (required): Full discussion URL (e.g., 'https://github.com/owner/repo/discussions/42')

What it does:

1. Fetches the current issue details
2. Extracts the discussion number from the URL
3. Adds or updates a discussion link at the top of the issue body
4. Updates the issue with the new body

Format: The discussion link is added as a blockquote at the top:

> **💬 Discussion:** [#42](https://github.com/owner/repo/discussions/42)

[Original issue body content...]

Requirements:

• GitHub CLI with authentication
• Permission to edit the issue
• Valid issue number and discussion URL

Returns:

• Confirmation with issue number, title, discussion number, and issue URL

Usage:

"Add discussion #42 to issue #15"
"Link the discussion to issue #20"

Example:

User: "Add discussion https://github.com/owner/repo/discussions/42 to issue #15"
AI: [Calls add_discussion_to_issue]
   ✅ Discussion link added to issue!
   Issue: #15 - Fix authentication bug
   Discussion: #42
   Issue URL: https://github.com/owner/repo/issues/15

Notes:

• If the issue already has a discussion link, it will be replaced with the new one
• The discussion link is added as a blockquote for visual distinction
• The original issue body content is preserved

Configuration

configure_project

Configure default project settings for this repository.

Parameters:

• owner (required): Project owner (org or user, e.g., 'PurpleDotStudio')
• number (required): Project number (e.g., 1)
• repo (required): Repository in format 'owner/repo' (e.g., 'PurpleDotStudio/my-repo')
• assignee (required): Default assignee username (e.g., 'andyjamesn')
• projectId (optional): Project's GraphQL node ID (e.g., 'PVT_kwDOBmeIvM4BGkkM'). Auto-detected if not provided

What it does:

1. Saves project settings to config.json
2. If projectId not provided, looks it up via GraphQL
3. Used by show_my_work, start_issue, and create_issue_from_todo

Stored configuration:

{
  "defaultProject": {
    "owner": "PurpleDotStudio",
    "number": 1,
    "repo": "PurpleDotStudio/my-repo",
    "assignee": "username",
    "projectId": "PVT_kwDOBmeIvM4BGkkM"
  }
}

Usage:

"Configure project for PurpleDotStudio/my-repo, project #1, assign to username"

Note: Run this once per repository to set up your workflow.

get_project_config

Get the current default project configuration.

Returns:

• Current project settings including owner, number, repo, assignee, projectId
• Current issue (if one is active from start_issue)

Usage:

"Show project config"
"What's my current project configuration?"

Workflow Example

User: "Show my work"
AI: [Lists tasks in Ready status]

User: "Start issue 42"
AI: [Fetches issue, moves to In Progress, loads context]

User: [Makes code changes]

AI: [Detects changes and suggests commit]
"I've updated the authentication flow. Ready to commit?"

User: "Yes, commit these changes"
AI: [Creates commit with message: "feat: update authentication flow\n\nCloses #42"]

Configuration File

The server stores configuration in config.json:

{
  "defaultProject": {
    "owner": "PurpleDotStudio",
    "number": 1,
    "repo": "PurpleDotStudio/my-repo",
    "assignee": "username",
    "projectId": "PVT_kwDOBmeIvM4BGkkM"
  },
  "currentIssue": {
    "number": 42,
    "title": "Update authentication flow",
    "url": "https://github.com/..."
  },
  "discussionCategories": {
    "repo": "PurpleDotStudio/my-repo",
    "repositoryId": "R_kgDOBmeIvM",
    "categories": [
      {
        "id": "DIC_kwDOBmeIvM4CXxyz",
        "name": "General",
        "description": "General discussions",
        "emoji": "💬"
      },
      {
        "id": "DIC_kwDOBmeIvM4CXxab",
        "name": "Ideas",
        "description": "Share ideas for new features",
        "emoji": "💡"
      },
      {
        "id": "DIC_kwDOBmeIvM4CXxcd",
        "name": "Q&A",
        "description": "Ask the community for help",
        "emoji": "❓"
      }
    ]
  }
}

Development

# Clone repository
git clone https://github.com/PurpleDotStudio/git-gogo-mcp
cd git-gogo-mcp

# Install dependencies
npm install

# Run locally
node index.js

Troubleshooting

"gh: command not found"

Install GitHub CLI: https://cli.github.com/

"insufficient OAuth scopes"

Refresh authentication with project scope:

gh auth refresh -s project

"No current issue found"

Use start_issue before calling commit_changes:

"Start issue 42"
[Make changes]
"Commit changes"

Config not persisting

Ensure the server has write permissions to its directory.

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT © Purple Dot Studio

Links

• GitHub Repository
• Model Context Protocol
• GitHub CLI Documentation