gitsu-mcp is a GitHub Projects MCP server: it ships inside the Gitsu desktop app, and its tools read and update a Projects v2 board. Any MCP client, such as Claude Code, Claude Desktop, Codex or Gemini, can use it to read a GitHub Projects v2 board and, while Gitsu is open, to change it. It has fifteen registered tool routes, although the extra app-only route is reserved for Gitsu's MCP Apps views. It requires a paid Seat through Pro or Team and runs only in the Gitsu desktop app for macOS. Gitsu also runs a hosted connector, https://dash.gitsu.app/api/mcp, that needs no desktop app and draws the same cards in Claude on the web, Claude Desktop and Claude mobile; the MCP views page covers where the cards show.
What tools does gitsu-mcp register to read, create and update Projects v2 items and fields?
It registers fifteen routes on its router: five model-facing local tools, nine write proxies, and one app-only route used by Gitsu's MCP Apps views. The list below is taken from the registration code in src-tauri/mcp/src/server.rs, the WRITE_TOOLS table in src-tauri/mcp/src/write.rs, and the view metadata in src-tauri/mcp/src/ui.rs. Tests fail the build if the count changes.
Five model-facing tools are answered by the server itself:
| Tool | What it does |
|---|---|
list_items | Reads the items on a board (issues, pull requests and drafts), one short row each. Filter on any column with fields, for example {"Priority": "P0"}; ask for more detail to add assignees, labels and URLs. |
get_item | Reads one item: its columns, labels, assignees, parent, sub-issue count, blockers and body, and on request its comments. |
list_projects | Lists the boards the signed-in user can see, with each one's id, owner and URL, and marks the one linked to the current folder. |
list_fields | Reads the board's columns, each column's type and, for select columns, the values it accepts. |
surface_info | Checks that the Gitsu app is running and reports its version and the caller name it saw. Reads and writes no board data. |
Nine tools are forwarded to the running Gitsu app, which performs the write:
| Tool | What it writes |
|---|---|
set_field_value | One project column on one item: Status, Priority, Estimate or any column the board declares. |
add_comment | One comment on the issue behind an item, with a hidden provenance mark. |
add_labels | Labels added from the repository's existing labels. Labels not named are left alone. |
remove_labels | Labels removed. Labels not named are left alone. |
close_item | Closes the issue, as completed or as not planned. |
reopen_item | Reopens a closed issue. |
start_work | Adds the agent-working label, which the board animates. |
finish_work | Removes the agent-working label. |
create_item | A new issue on the board, with a title, a body carrying the provenance mark, and any column values named. |
There is no tool that assigns a person, sets a milestone, deletes anything or removes an item from a board.
open_in_gitsu is the fifteenth route. It is not a board read or write: a Gitsu MCP Apps view calls it to send a gitsu:// link to the running desktop app. When the host advertises io.modelcontextprotocol/ui, Gitsu marks the route with visibility: ["app"], so the model never sees it. A host without MCP Apps receives the original fourteen routes. The MCP Apps views page explains the five shipped view families, the host capability check, and the read and write boundaries they keep.
How do I turn it on?
You do not have to. At every launch the Gitsu desktop app adds gitsu-mcp to the MCP configuration of each supported coding agent it finds on your Mac. Settings, MCP server, lists those agents as Connected or Disconnected, with the ones that are not installed behind a Show not installed link. Disconnect an agent and Gitsu removes gitsu-mcp from its configuration and leaves it out from then on.
Writes are on by default. One switch in the same section, Agents can write to your boards, turns them off for every agent at once; reads keep working.
You can also register the binary with an MCP client by hand, as the developer guide shows for Claude Code: claude mcp add gitsu -- /abs/path/to/gitsu-mcp --stdio. Step-by-step setup for Claude Code, Claude Desktop and Cursor is in connect Claude to GitHub Projects, and connect GitHub to Claude shows which Claude apps can use the server at all.
How does it find my board?
It uses the folder your agent is working in. The server reads the folder's git remote and uses the board in Gitsu that holds that repository's issues. If Gitsu has none cached, it uses the board linked to the repository on GitHub. If the repository has several boards, it uses the one open in the running Gitsu app, or failing that the one you opened most recently, and the answer names that board and lists the others. Only when neither applies does it list every board for the agent to choose from. Board selection walks through each case. Every answer starts with the board it read and says when the board was discovered rather than named, so a wrong guess is visible. Pass project_id to name a board directly, which is the only way to reach a board Gitsu has not cached and no repository links to.
What does it refuse to do?
- Write without the app. The server never writes to GitHub itself. Each write goes over a local socket to the running Gitsu app, which is the only place writes are checked and performed. With the app closed, the write fails with a message for you: open Gitsu and ask again. Nothing is queued.
- Report success early. A write answers only after GitHub accepts or refuses it. If the app quits mid-call, the answer says the result is unknown and tells the agent to re-read before retrying.
- Accept guessed column values. A column or value the board does not have is refused, and the refusal lists the ones it does have.
- Use a second sign-in. The server reads the GitHub token the desktop app stored in the macOS keychain. Signing out of Gitsu cuts it off too.
How writes are limited and marked is covered on agent safety.
Who is it for?
It suits developers who already run a coding agent in a repository and keep the work in GitHub Projects. The agent can read the P0 items on the board, pick one, mark it as being worked on, and close it with a comment when it is done, while you watch the board update in the Gitsu window.
If you only want to browse and edit boards, the free Web App covers that without an install. The getting started guide walks through signing in and importing boards.
How we checked
The complete tool route list of the gitsu-mcp binary, copied from its registration and view metadata code, with what each tool reads or writes, the app-only open_in_gitsu relay, and the refusals the relay returns.
Frequently asked questions
Is there an MCP server for GitHub Projects?
Yes. gitsu-mcp reads a GitHub Projects v2 board and, while the Gitsu desktop app is open, creates, moves and closes its items. It finds the board from the git remote of the folder your agent is in. It requires a paid Seat. GitHub also publishes its own MCP server; the Claude Code setup guide covers what that one does and does not do for Projects.
Which tools does the Gitsu MCP server register?
Fifteen routes are in its router. Five are answered locally: list_items, get_item, list_projects, list_fields and surface_info. Nine are forwarded to the running Gitsu app: set_field_value, add_comment, add_labels, remove_labels, close_item, reopen_item, start_work, finish_work and create_item. The fifteenth, open_in_gitsu, is an app-only route for Gitsu's MCP Apps views. A host without MCP Apps omits it, and a compatible host marks it for the app rather than the model.
Can an agent delete issues or project items through it?
No. The write list is closed at nine tools, and none of them deletes an issue, removes an item from a board or edits a draft. The app-only open_in_gitsu route only opens a gitsu:// link in the running app. The list length is pinned by a test, so adding a tool fails the build until someone reviews it.
Does the MCP server work with the Gitsu app closed?
The board reads do: list_items, get_item, list_projects and list_fields can read GitHub with the token the app stored in your keychain. surface_info checks the running app, open_in_gitsu is an app-only view action, and writes need the app too. With the app closed a write fails with a message to pass on to you: open Gitsu and ask again. Nothing is queued for later.
Is there an MCP server for the Gitsu Web App?
No. The MCP server is a desktop binary that reads the sign-in token from the macOS keychain, and the Web App keeps its token on the server. In the Web App, Settings says the MCP server runs in the desktop app and requires a paid Seat through Pro or Team.
How does it know which board to read?
It takes the folder your agent is working in, reads that repository's git remote, and uses the GitHub Projects board that holds the repository's issues, or failing that the board linked to the repository. Every answer names the board it read. Pass project_id to choose a different board.
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