To integrate GitHub Issues with an AI agent, give the agent an authenticated GitHub interface: gh for shell access, GitHub MCP for MCP clients, or Gitsu MCP for GitHub Projects board work. Start by reading a known issue and checking its repository or board before asking the agent to make changes.
An issue number alone is incomplete context. Include the repository, the task and whether the agent should only read or also change the issue.
Which GitHub Issues integration should I choose?
Choose the interface your agent can use and the scope of work it needs to read.
| Agent task | Connection to consider | Why it fits |
|---|---|---|
| Read repository issues from a shell | Authenticated GitHub CLI, gh | Explicit repository flags and structured JSON output |
| Read GitHub issues through MCP tools | GitHub's official MCP server | GitHub operations exposed to MCP clients |
| Read or update items on a GitHub Projects board | Gitsu MCP | Board fields, local cached reads and writes through the desktop app |
GitHub Issues and GitHub Projects are related but different scopes. A repository can contain an issue that is on no Projects board. Gitsu's MCP interface works with board items, so it is not a replacement for repository-wide issue search.
How do I connect a shell agent with the GitHub CLI?
Install gh, authenticate it with GitHub, and let the agent run issue reads against an explicit repository.
The GitHub authentication manual documents:
gh auth login
Then list open issues with selected JSON fields:
gh issue list --repo OWNER/REPO --state open --limit 50 \
--json number,title,url,labels
Replace OWNER/REPO with the actual repository. The limit is an example, not a declaration that the result includes every open issue. The issue-list manual documents filtering, limits and JSON fields.
Read a known issue before handing over the task:
gh issue view 42 --repo OWNER/REPO --comments
Replace 42 with its actual number. The issue-view manual covers reading the issue and its comments. This path works through the agent's shell; it does not require an MCP registration.
How do I connect an MCP agent to GitHub Issues?
Register GitHub's official MCP server in an MCP-capable client using that client's supported authentication and configuration path.
The official server repository provides remote and local server setup plus client installation instructions. Use the instructions for the client being configured, then verify that issue tools are available. Add Projects support when the task also needs a board's fields and items.
The existing Claude Code and Cursor connection guide supplies those client-specific steps for Projects. This reference focuses on choosing an interface and verifying issue access.
How do I connect the agent to Gitsu MCP?
Open the Gitsu desktop app, sign in, connect its bundled MCP server to the agent, and select the board the agent will use.
Gitsu registers its bundled server with supported coding agents it detects. A manual registration uses the actual sidecar path. For Claude Code, the documented command shape is:
claude mcp add gitsu -- /absolute/path/to/gitsu-mcp --stdio
The path is a placeholder. Use the bundled binary's real path. MCP access requires a paid Seat through Pro or Team; the current plans are on pricing.
Use list_items for matching board items and get_item for one item's details. Pass project_id when the board must be explicit. The board selection reference explains discovery and overrides. Writes need the running desktop app; agent safety describes their boundaries.
What is the fastest way to get GitHub issues into my agent?
For board items already loaded in Gitsu, the local MCP read path can avoid another GitHub round trip; recorded cached list_items calls took 4–7 ms.
That is tool-call latency measured on a test board. It excludes the agent's reasoning and is not a universal ranking against gh or GitHub MCP. The measurement article states the conditions and separates cached item reads from earlier GitHub-backed reads. Per-call timings for gh, gh-axi and GitHub MCP are unavailable, but task-level timings exist: the same article has a benchmark of nine whole agent tasks through all four tools, with its caveats.
For repository issues outside that board, choose an interface that reaches them, such as gh or GitHub MCP. For a decision requiring a fresh GitHub item read through Gitsu, call get_item with fresh: true and check the response source line.
How do I verify the integration before assigning work?
Ask for a read-only summary of one known issue and verify the destination and answer.
- Name the repository and issue number, or the Projects board and item.
- Ask the agent to read its title, body and current state.
- Check the returned URL against the issue you intended.
- For Gitsu, also check the board headline, source and cache age.
- Assign the implementation or update only after that read matches.
A useful first prompt is:
Read issue #42 in OWNER/REPO. Summarize its requested outcome and current
state, and include its URL. Do not change the issue yet.
Replace the number and repository. Once access is verified, the GitHub issues workflow covers handing over work and reviewing the result.
How we checked
Gitsu's board-only read boundary, cached list_items measurements, explicit board selection and app-relayed writes, set beside the documented GitHub CLI commands and GitHub MCP connection options.
Frequently asked questions
How do I integrate GitHub Issues with my AI agent?
Use authenticated gh commands for an agent with shell access, or register a GitHub MCP server in an MCP-capable client. Use Gitsu MCP for GitHub Projects board work and verify the selected board before asking the agent to change items.
What is the fastest way to get GitHub issues into my agent?
For issues on a board already loaded in Gitsu, its MCP server can reuse local data: recorded cached list_items reads took 4–7 ms. Per-call timings for the alternatives are unavailable, so this does not establish a universal fastest tool. A task-level benchmark timed nine whole agent tasks with each tool; its results and limits are on the Gitsu MCP local reads page. For repository-wide issue access, use gh or GitHub MCP.
Do I need MCP to let an agent read GitHub issues?
No. An agent that can run shell commands can use authenticated gh issue list and gh issue view commands. MCP is another interface for clients that support it.
Can Gitsu MCP read every issue in a repository?
Gitsu MCP is a board-oriented interface. Its issue reads operate on GitHub Projects items; an issue outside the board is outside that interface. Use gh or GitHub MCP when the task is repository-wide.
Try it on your own boardsGitsu opens your GitHub Projects boards in the browser. Sign in with GitHub and work on the same issues your team already uses.
Open the Web App