Github-Issues

# GitHub Issues

Manage GitHub issues using the `@modelcontextprotocol/server-github` MCP server.

Available Tools

MCP Tools (read operations)

| Tool | Purpose |

|------|---------|

| `mcp__github__issue_read` | Read issue details, sub-issues, comments, labels (methods: get, get_comments, get_sub_issues, get_labels) |

| `mcp__github__list_issues` | List and filter repository issues by state, labels, date |

| `mcp__github__search_issues` | Search issues across repos using GitHub search syntax |

| `mcp__github__projects_list` | List projects, project fields, project items, status updates |

| `mcp__github__projects_get` | Get details of a project, field, item, or status update |

| `mcp__github__projects_write` | Add/update/delete project items, create status updates |

CLI / REST API (write operations)

The MCP server does not currently support creating, updating, or commenting on issues. Use `gh api` for these operations.

| Operation | Command |

|-----------|---------|

| Create issue | `gh api repos/{owner}/{repo}/issues -X POST -f title=... -f body=...` |

| Update issue | `gh api repos/{owner}/{repo}/issues/{number} -X PATCH -f title=... -f state=...` |

| Add comment | `gh api repos/{owner}/{repo}/issues/{number}/comments -X POST -f body=...` |

| Close issue | `gh api repos/{owner}/{repo}/issues/{number} -X PATCH -f state=closed` |

| Set issue type | Include `-f type=Bug` in the create call (REST API only, not supported by `gh issue create` CLI) |

**Note:** `gh issue create` works for basic issue creation but does **not** support the `--type` flag. Use `gh api` when you need to set issue types.

Workflow

1. **Determine action**: Create, update, or query?

2. **Gather context**: Get repo info, existing labels, milestones if needed

3. **Structure content**: Use appropriate template from [references/templates.md](references/templates.md)

4. **Execute**: Use MCP tools for reads, `gh api` for writes

5. **Confirm**: Report the issue URL to user

Creating Issues

Use `gh api` to create issues. This supports all parameters including issue types.

gh api repos/{owner}/{repo}/issues \
  -X POST \
  -f title="Issue title" \
  -f body="Issue body in markdown" \
  -f type="Bug" \
  --jq '{number, html_url}'

Optional Parameters

Add any of these flags to the `gh api` call:

-f type="Bug"                    # Issue type (Bug, Feature, Task, Epic, etc.)
-f labels[]="bug"                # Labels (repeat for multiple)
-f assignees[]="username"        # Assignees (repeat for multiple)
-f milestone=1                   # Milestone number

**Issue types** are organization-level metadata. To discover available types, use:

gh api graphql -f query='{ organization(login: "ORG") { issueTypes(first: 10) { nodes { name } } } }' --jq '.data.organization.issueTypes.nodes[].name'

**Prefer issue types over labels for categorization.** When issue types are available (e.g., Bug, Feature, Task), use the `type` parameter instead of applying equivalent labels like `bug` or `enhancement`. Issue types are the canonical way to categorize issues on GitHub. Only fall back to labels when the org has no issue types configured.

Title Guidelines

- Be specific and actionable

- Keep under 72 characters

- When issue types are set, don't add redundant prefixes like `[Bug]`

- Examples:

- `Login fails with SSO enabled` (with type=Bug)

- `Add dark mode support` (with type=Feature)

- `Add unit tests for auth module` (with type=Task)

Body Structure

Always use the templates in [references/templates.md](references/templates.md). Choose based on issue type:

| User Request | Template |

|--------------|----------|

| Bug, error, broken, not working | Bug Report |

| Feature, enhancement, add, new | Feature Request |

| Task, chore, refactor, update | Task |

Updating Issues

Use `gh api` with PATCH:

gh api repos/{owner}/{repo}/issues/{number} \
  -X PATCH \
  -f state=closed \
  -f title="Updated title"