Gh Issues

gh-issues-mcp

A Model Context Protocol (MCP) server that exposes a fixed, narrow set of GitHub Issues tools, scoped to a configured allowlist of repositories. It runs as its own long-running process, outside the process tree of any agent session, and holds a GitHub personal access token internally so agents never see or hold the credential themselves.

Requirements

• Node.js
• macOS (the token is read from the macOS Keychain)
• An MCP client that supports Streamable HTTP transport (Claude Code, Claude Desktop, VS Code, Cursor, or any other MCP client)

Quickstart

1. Create a token. Create a fine-grained personal access token, scoped to every repo you plan to track (the repos you'll list under repos in step 3). Grant only:

   • Issues: Read and write
   • Metadata: Read-only

   Nothing else — see Token scope for why.

2. Store it in the Keychain — the server only ever reads the token from here, never from an env var or a file:

   security add-generic-password \
     -a "$USER" \
     -s "gh-issues-mcp" \
     -T "" \
     -w
   

   -w with no value prompts for the token instead of taking it as an argument, so it never lands in your shell history. The first time a process reads it back, macOS prompts you to click Allow. See Keychain storage for what -T "" does and how to replace a token later.

3. Point it at your repo. Create ~/.config/gh-issues-mcp/config.json:

   {
     "repos": [{ "repo": "joachimwedin/gh-issues-mcp" }],
     "port": 4319
   }
   

   repos is an allowlist — every repo a tool call may target — and with one entry it's the implicit default. To track more than one repo, list them all here and add defaultRepo to pick which one a call uses when it omits the repo parameter. See Configuration for the full schema, including per-repo label vocabulary overrides.

4. Install and start the server, then confirm it picked up the token:

   npm install
   npm run build
   npm start
   

   curl http://127.0.0.1:4319/health
   # {"status":"ok","tokenLoaded":true}
   

   It's meant to be started once and left running — there's no auto-start or service-management logic built in.

5. Register it with your MCP client. The port is machine-specific and the server is meant to be available to every agent session on the machine, not just one project — register it at the user level, not project-local.

   Standard config works in most clients:

   {
     "mcpServers": {
       "gh-issues-mcp": {
         "url": "http://127.0.0.1:4319/mcp"
       }
     }
   }
   

   Claude Code

   claude mcp add --transport http gh-issues-mcp http://127.0.0.1:4319/mcp --scope user
   

   Claude Desktop

   Follow the MCP install guide, use the standard config above.

   VS Code

   code --add-mcp '{"name":"gh-issues-mcp","url":"http://127.0.0.1:4319/mcp"}'
   

   Cursor

   Go to Cursor Settings -> MCP -> Add new MCP Server. Use the standard config above.

Key Features

• Narrow surface. Nine tools, all issue-scoped and restricted to a configured repo allowlist — nothing in the tool set can touch code, pull requests, or repo administration.
• Token isolation. The GitHub token lives only in the macOS Keychain and this process; agents talk to a local HTTP endpoint, never to GitHub directly.
• Local-only. Binds to 127.0.0.1 only — never reachable from outside the machine it runs on.
• Audited. Every tool call is appended to a local JSON-lines audit log, independent of GitHub's own issue-timeline history.

Configuration

The server has no command-line flags — it reads runtime settings from environment variables and a JSON config file.

{
  /** Allowlist of repos tool calls may target. Non-empty. */
  repos: {
    /** "owner/name". */
    repo: string;

    /**
     * Allowed label values for edit_labels and create_issue on this repo.
     * Labels outside this list are rejected locally, before any GitHub API
     * call is made. Defaults to needs-triage, needs-info, ready-for-agent,
     * ready-for-human, wontfix.
     */
    labelVocabulary?: string[];
  }[];

  /**
   * The repo a tool call targets when it omits the `repo` parameter. Must
   * be one of the "owner/name" values in `repos`. Optional only when
   * `repos` has exactly one entry, in which case that entry is the default.
   */
  defaultRepo?: string;

  /** Port the server listens on. Bound to 127.0.0.1 only, never external. */
  port: number;
}

Security

gh-issues-mcp is designed so that a compromised server process, or a bug in a tool handler, cannot do more damage than commenting on or labeling issues.

security add-generic-password \
  -a "$USER" \
  -s "gh-issues-mcp" \
  -T "" \
  -w

security delete-generic-password -s "gh-issues-mcp"

Tools

Every tool below (except list_repos) takes an optional repo parameter, "owner/name", which must be one of the configured repos allowlist entries — a call naming a repo outside it is rejected locally, before any GitHub API call is made. When omitted, the call falls back to defaultRepo. Every issue-shaped result (all tools except edit_labels and list_repos) is tagged with the repo it targeted.

• list_issues

  • Description: List issues in a repository, optionally filtered by state and labels. Pull requests are excluded, since this server treats issues, not PRs, as the triage surface.
  • Parameters:
    • repo (string, optional): "owner/name". Defaults to defaultRepo.
    • state (string, optional): One of open, closed, all.
    • labels (array, optional): Labels to filter by.
    • includeComments (boolean, optional): When true, each returned issue also carries its full comment history (same shape view_issue returns), fetched only for the filtered result set. Defaults to false — no shape change, no extra GitHub calls.
  • Read-only: true

• view_issue

  • Description: View a single issue's body, labels, and full comment history.
  • Parameters:
    • repo (string, optional): "owner/name". Defaults to defaultRepo.
    • number (integer): Issue number.
  • Read-only: true

• comment_issue

  • Description: Post a comment to the given issue.
  • Parameters:
    • repo (string, optional): "owner/name". Defaults to defaultRepo.
    • number (integer): Issue number.
    • body (string): Comment body.
  • Read-only: false

• close_issue

  • Description: Post a comment and close the given issue. comment is required, so an issue can never be closed without an explanation.
  • Parameters:
    • repo (string, optional): "owner/name". Defaults to defaultRepo.
    • number (integer): Issue number.
    • comment (string): Closing comment. Required — the call is rejected locally if omitted.
  • Read-only: false

• edit_labels

  • Description: Add and/or remove labels on the given issue, restricted to the resolved repo's configured label vocabulary. Labels outside the vocabulary are rejected locally, before any GitHub API call is made. Unlike the other write tools, the result is { repo, labels } — the resolved repo plus the issue's resulting label list — rather than a tagged issue object.
  • Parameters:
    • repo (string, optional): "owner/name". Defaults to defaultRepo.
    • number (integer): Issue number.
    • add (array, optional): Labels to add.
    • remove (array, optional): Labels to remove.
  • Read-only: false

• create_sub_issue

  • Description: Create a new issue and link it as a sub-issue of the given parent issue, via GitHub's sub-issues API. Both the parent and the new sub-issue are in the same repo.
  • Parameters:
    • repo (string, optional): "owner/name". Defaults to defaultRepo.
    • parent_number (integer): Parent issue number.
    • title (string): Title of the new sub-issue.
    • body (string): Body of the new sub-issue.
  • Read-only: false

• create_issue

  • Description: Create a new top-level issue in a repository. Labels outside the resolved repo's configured vocabulary are rejected locally, before any GitHub API call is made.
  • Parameters:
    • repo (string, optional): "owner/name". Defaults to defaultRepo.
    • title (string): Issue title.
    • body (string): Issue body.
    • labels (array, optional): Labels to apply, restricted to the resolved repo's configured vocabulary.
  • Read-only: false

• edit_issue

  • Description: Update an issue's title and/or body. At least one of title/body must be given — a call with neither is rejected locally, before any GitHub API call is made.
  • Parameters:
    • repo (string, optional): "owner/name". Defaults to defaultRepo.
    • number (integer): Issue number.
    • title (string, optional): New title.
    • body (string, optional): New body.
  • Read-only: false

• list_repos

  • Description: List the configured repo allowlist and each repo's effective label vocabulary (its own override, or the server-wide default). Takes no parameters — it doesn't target a single repo, so it has no repo input and its results aren't tagged with one.
  • Parameters: none.
  • Read-only: true