How to connect GitHub Issues to Claude Code

A terminal with gh auth login and the address of GitHub's MCP server, connected to a GitHub repository whose issues Claude Code can read and update.

CRUX team · · Commands checked on · 6 min read

The shortest way for one developer is the GitHub CLI: run gh auth login once, and Claude Code reads and writes GitHub issues by running gh commands in your terminal. If you want MCP tools, add GitHub's official MCP server at https://api.githubcopilot.com/mcp with one claude mcp add-json command and a personal access token. GitHub calls the unit of work an issue, and this article calls it a task.

How do I connect GitHub Issues to Claude Code?

Option 1. The GitHub CLI. You need gh installed and a GitHub account that can open the repository. Sign in through the browser:

gh auth login

If your statuses live on a GitHub Projects board, add the project scope:

gh auth refresh -s project

Claude Code's documentation says that with gh installed and signed in, Claude opens pull requests and reads review comments without extra instructions, and that a tool's CLI is usually the easiest way in.

Option 2. GitHub's remote MCP server. GitHub hosts it. You need a personal access token: GitHub's Claude guide says to check that it has the repo scope (a scope of classic tokens), and Claude Code's documentation suggests a fine-grained token with access to the repositories you want. Run this in the terminal, not inside Claude Code:

claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}'

GitHub gives this form for Claude Code 2.1.1 and newer. For older versions, or when add-json returns Invalid input on Windows, GitHub gives this one:

claude mcp add --transport http github https://api.githubcopilot.com/mcp -H "Authorization: Bearer YOUR_GITHUB_PAT"

Either command stores an entry like this in your Claude Code configuration. Keep the token out of a .mcp.json file that you commit.

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_GITHUB_PAT"
      }
    }
  }
}

Restart Claude Code. Sign-in here is the token in the header: neither GitHub nor Anthropic documents an OAuth sign-in through /mcp for the remote server.

Option 3. The same server, local, in Docker. On github.com it needs no token: on first use Claude Code asks to open GitHub's sign-in page in your browser, and the token stays in memory only.

claude mcp add github -e GITHUB_OAUTH_CALLBACK_PORT=8085 -- docker run -i --rm -p 127.0.0.1:8085:8085 -e GITHUB_OAUTH_CALLBACK_PORT ghcr.io/github/github-mcp-server

How do I check that the connection works?

For the CLI:

gh auth status
gh issue list

For the MCP server:

claude mcp list
claude mcp get github

Inside Claude Code, /mcp shows the server's status. Then ask Claude Code to read one task by its number.

What can Claude Code do in GitHub Issues after that, and what can it not do?

With no extra settings the MCP server enables five toolsets: context, repos, issues, pull_requests and users. Through the issues toolset Claude Code can:

  • read a task with its comments, labels, sub-issues and parent;
  • list and search tasks;
  • create a task and update its title, body, labels, assignees and state;
  • add and edit comments, and change sub-issues.

The limits:

  • The projects toolset is off by default. Turn it on with the X-MCP-Toolsets header, for example issues,projects; the address https://api.githubcopilot.com/mcp/x/projects gives the Projects tools alone. Its tools ask for the read:project scope to read and project to write. With it Claude Code can set a field such as Status on a board item.
  • The issues toolset has no tool that deletes a task. The CLI has gh issue delete.
  • For read-only access, add /readonly to the address or send the X-MCP-Readonly header.
  • The remote server does not work with GitHub Enterprise Server. The local server does, with GITHUB_HOST and a token.
  • With a classic token, the server hides the tools whose scope the token lacks.
  • Claude Code acts as you, with the rights of your token.

What about @claude in GitHub Actions?

That is a separate product. Claude Code GitHub Actions runs Claude Code in your repository's workflows, not on your machine. You need admin access to a github.com repository and gh signed in. Run this inside Claude Code:

/install-github-app

The command installs the Claude GitHub App, saves an ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN repository secret, and opens a pull request with the workflow file. After you merge it, mention @claude in an issue or pull request comment, and Claude replies in a comment on the same issue or pull request. Only people with write access to the repository can trigger it. The details are in Claude Code GitHub Actions.

What changes when three or more people do this?

The server and gh connect one person's agent to GitHub. They do not say who does what in a team. With three or more people you meet these situations:

  • A task sits in "In review" and no role owns that status. Nobody knows who starts the next step or who approves it.
  • Ryan asks the agent for a plan before code. Another developer keeps different prompts and skips the plan. The result depends on who took the task.
  • Emily, the PM, answers the agent's question in Ryan's chat. Megan tests the task a week later and never sees that answer.
  • Ryan's session waits for Emily's answer. Emily does not know that a session waits for her.

How does CRUX handle the team part?

We build CRUX, so this part is about our own product, and it is in beta.

What the agent needs to know about the project is already in GitHub: the task, its parent and the decisions already on it. CRUX lets the agent read that, and each status in your workflow has its own instructions, so nobody writes a prompt. CRUX is the workflow layer between a team's tracker and the coding agents the team already uses.

  • CRUX connects through the CRUX GitHub App. Tasks are GitHub issues.
  • A GitHub Projects board is optional. Statuses come from the board's Status field when there is one, and from labels named S:<NAME> when there is not.
  • A CRUX project is one repository plus at most one board.
  • Each status has an owner role. A person starts each step and approves the result at approval checkpoints.
  • Each step posts its artifact as a comment on the task.
  • CRUX does not attach files or delete tasks on GitHub, and it does not support GitHub Enterprise Server.

When is the plain MCP server enough?

  • You work alone.
  • One person starts and reviews all the agent's work.
  • You need the agent to read tasks and post comments, and people move statuses by hand.
  • The job is a single pass, such as labeling new tasks.
  • You use GitHub Enterprise Server.

FAQ

Is there an official GitHub MCP server?

Yes. It is github/github-mcp-server. GitHub hosts a remote version and publishes a local one as a Docker image and a binary.

Do I need a personal access token?

For the remote server in Claude Code, GitHub's guide uses one. The local Docker server on github.com and gh sign in through the browser.

Can Claude Code change a status on a GitHub Projects board?

Yes, with the projects toolset and the project scope, or with gh project item-edit.

Should I use the MCP server or gh?

Use gh if it is already on your machine. Use the MCP server when you want read-only mode or a fixed set of tools.

Try this on your own project. CRUX is free for one person, no card.

Start free

Next: Stop writing prompts: why AI coding agents need a workflow

All articles