Connect Claude Code to GitHub Projects with MCP

An MCP server is what lets Claude Code or Cursor read your GitHub Projects board and change it. Two servers do this today: GitHub's official MCP server and the one that ships inside the Gitsu desktop app. They make different trade-offs, and you can run both.

This guide sets up each one in Claude Code and in Cursor and says what the agent can read and write under each. Once a server is connected, the Claude Code GitHub issues workflow shows how to run an issue from pick-up to review.

Which MCP server should you use for GitHub Projects?

Use GitHub's official server if you want the widest reach and no extra app: repositories, pull requests, Actions and Projects, from any MCP client on any operating system. Use Gitsu's server if you want an agent to write to your board inside fixed limits, and you already run the Gitsu desktop app.

GitHub's server wins on breadth. It can create a project, add an issue to one and delete an item, and Gitsu's cannot do any of those. Gitsu's server wins on bounding what an agent may do to a board you care about.

What does GitHub's official MCP server cover for Projects?

GitHub's server covers Projects through a projects toolset, and that toolset is off by default. The default set is context, repos, issues, pull_requests and users, so a server added with the standard URL cannot see your board until you turn Projects on.

With the toolset on, three tools appear:

• projects_list lists projects, their fields, items, views and status updates. It accepts GitHub's project filter syntax, and it returns only titles unless you pass the field names you want.
• projects_get reads one project, field, item, view or status update.
• projects_write creates a project, adds an issue or pull request to one, updates or deletes items (up to 50 per batch update), creates iteration fields, manages views and posts status updates.

Reads ask for the read:project scope and writes for project, according to the README. What it does not do is decide which board you mean: every call names an owner and a project number.

How do you add GitHub's MCP server to Claude Code?

Run GitHub's documented command with your token in place of the placeholder:

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

That registers the hosted server with the default toolsets. To reach your board, GitHub's remote-server table gives Projects its own URL, https://api.githubcopilot.com/mcp/x/projects, and a read-only one at https://api.githubcopilot.com/mcp/x/projects/readonly. Register the Projects URL under a second name if you want both sets of tools.

Check the result with claude mcp list, then ask the agent to list the projects on your account.

How do you add GitHub's MCP server to Cursor?

Open ~/.cursor/mcp.json and add GitHub's documented entry, then restart Cursor:

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

GitHub's guide notes that this needs Cursor 0.48.0 or later and that the hosted server takes a personal access token rather than OAuth in Cursor. As in Claude Code, swap the URL for the Projects one to see your board.

What does Gitsu's MCP server cover?

Gitsu's server answers two read tools itself and passes ten more to the running app:

• Reads, with the app closed: list_items filters on state, assignee, label, title search, archived, and any column on the board. list_fields lists the board's columns and the values each one accepts.
• Writes, through the app: set_field_value, add_comment, add_labels, remove_labels, close_item and reopen_item.
• Housekeeping: request_write_budget asks for write allowance, start_work and finish_work put and remove an agent-working label so the board shows the item is in progress, and surface_info checks that the app is running without reading or writing board data.

Two behaviours set it apart. It works out which board you mean from the folder the agent runs in: it reads the folder's git remote and uses the one project linked to that repository, and every answer names the board it read. And it filters on a board's own columns by name, so a Priority column is one argument:

{ "fields": { "Priority": "P0" } }                    // the P0 items
{ "fields": { "Priority": "P0", "Status": "Todo" } }  // AND, like every other filter

A wrong guess comes back with the real vocabulary, such as the values Priority accepts, instead of an empty list.

Which Gitsu capabilities need the desktop app?

All of them. The MCP server, the agent panel and the agent-safety layer are part of the desktop app, and the desktop app is Gitsu Pro. The free plan is the web app, and its plan card lists AI access and the desktop app as not included. The server also needs macOS or Linux: on any other platform Gitsu refuses to enable it.

Reads work while the app is closed, because the server reads GitHub with the token the app stored. Writes do not. With the app closed, a write fails with an error telling the agent to start Gitsu, and nothing is queued to land later.

How do you connect Gitsu's MCP server to Claude Code or Cursor?

Turn it on from the app. In the Gitsu desktop app, open Settings, then MCP server, and switch on Claude Code, Cursor or any other listed agent. That switch does two things at once: it writes the server into the agent's own config file, and it grants that agent write access. Turning the switch off removes the entry and revokes access.

The entry Gitsu writes starts from this spec in its source:

export const GITSU_MCP_SPEC: Record<string, unknown> = {
  type: 'stdio',
  command: GITSU_MCP_SERVER_ID,
  args: ['--stdio'],
}

Before writing, Gitsu replaces command with the absolute path of the server inside the app bundle, and it re-checks that path each time the app launches so a moved app does not leave a broken entry. For Claude Code the entry lands under mcpServers in ~/.claude.json. For Cursor it lands under mcpServers in ~/.cursor/mcp.json, with only the command and args keys, because Cursor tells server types apart by shape and has no type key.

You can also register it by hand in Claude Code with the line from Gitsu's developer docs, using the real path to the server:

claude mcp add gitsu -- /abs/path/to/gitsu-mcp --stdio

A hand-registered server can read at once. It still needs the agent switched on in Settings before any write succeeds, because the app checks that list on every write.

What can the agent write through Gitsu, and what stops it?

The agent can change one item per call: set a field, add or remove labels, comment, close or reopen. It cannot create an issue, delete anything, remove an item from a project, or change assignees or milestones, because no tool for those exists.

Inside that set, three limits apply:

• A write budget. The agent asks for a number of writes with a reason, and the app grants it against a ledger. The budget belongs to that one agent process and expires after an hour at most.
• Server-confirmed replies. A write reports success only after GitHub accepts it. If the app quits mid-call, the agent is told the result is unknown and to re-read before retrying.
• A trace. Comments the agent writes carry a hidden marker, and every agent write goes into the app's activity log, so you can tell its changes from yours.

Gitsu's own decision record states the limit of this. The app can prove that a caller is its own server, but it cannot prove which agent launched that server, so the per-agent switches are consent settings rather than a security boundary. The case for letting an agent write rests on what the tools cannot do. The page on letting an AI agent update GitHub issues safely explains that design.

How do you check that the connection works?

Ask the agent a read question first, such as "list the P0 items on this board". A read touches nothing, so it is a safe test of both servers.

With GitHub's server, the answer should list items from the project you named. If the agent says it has no Projects tools, the server is registered with the default toolsets; register the Projects URL.

With Gitsu's server, every answer starts by naming the board it read and says when that board was discovered from your folder. If it is the wrong board, pass project_id to choose another. Four other answers point at a setup problem:

• The server fails to start. You are signed out of the Gitsu app. The server reads the stored token when it starts, before the agent connects, so it fails early rather than answering with errors later.
• It lists several boards. The repository is linked to more than one project. Pick one by its ID.
• It finds no board. The board is linked to no repository, or the folder has no git remote. A board like that is reachable only by passing its ID.
• Writes are refused. The desktop app is closed, or the agent is not switched on under Settings → MCP server.

Where to go next

With either server connected, the Claude Code GitHub issues workflow walks through handing an issue to the agent and reviewing what it did. If you are new to Gitsu, getting started with the Gitsu Web App covers sign-in and choosing boards.