Github MCP Server

GitHub MCP Server (@sumirati/mcp-github)

A modern, 2026 AI-native Model Context Protocol (MCP) server for GitHub REST API, engineered for autonomous AI agents and developer workflows.

---

What makes v2 Unique: The 2026 5-Tool Hybrid Standard

In early MCP servers, exposing 50–100+ eager tool definitions flooded every LLM turn with thousands of redundant schema tokens ("System Prompt Tax") and degraded reasoning coherence.

Architecturally aligned with @sumirati/mcp-gitlab, @sumirati/mcp-github solves this with a 5-Tool Hybrid Surface:

• Glama TDQS Coherence Tier A (5/5): By exposing exactly 5 tools to the client, the server sits in the ideal 3–15 tool coherence sweet spot.
• Ultra-Lean System Prompt Tax: Drops schema overhead from ~14.7k tokens down to ~450 tokens (97% reduction), preserving context windows and maximizing LLM prompt-cache hits.
• Zero-Hop Hourly Drivers: The 3 operations developers and agents use constantly (get_file_contents, get_repository, get_commit) remain eager tools for instant zero-hop execution.
• 100% Platform Access on Demand: The entire platform surface of 79 actions across 13 domains is accessible on-demand via dynamic action discovery (github_find_actions $\rightarrow$ github_execute_action), supporting both JSON and Markdown output (format: "json" | "markdown").
• Resilient Fallback: If an agent directly invokes any catalog action name (e.g. list_pull_requests), the server dynamically executes it with full input validation and projection.

LLM Prompt Context (~450 tokens total):
├── 1. github_find_actions(query, [domain], [format])     [Meta Discovery]
├── 2. github_execute_action(action, params, [format])   [Meta Dynamic Execution]
├── 3. get_file_contents(owner, repo, path)               [Eager Daily Driver #1]
├── 4. get_repository(owner, repo)                        [Eager Daily Driver #2]
└── 5. get_commit(owner, repo, ref)                       [Eager Daily Driver #3]

Under the hood (Dynamic Registry):
└── 79 Curated Actions across 13 Domains (with 70%+ token reduction projections)

---

Core Capabilities Across 13 Domains

1. Enterprise Observability & Diagnostics: End-to-end API latency, authentication verification, remaining rate limits, and read-only status (system_health_check).
2. Repositories & Governance: Full repository lifecycle, branch management, branch protection rules (get_branch_protection), file reading (auto Base64-decoded), atomic multi-file commits, and repository topics.
3. Pull Requests & Code Reviews: PR lifecycle (create, update, merge), review comments, inline diff reviews, and two-stage diff inspection with lockfile filtering.
4. Issues & Milestones: Issue tracking, milestone assignment, progress notes, and label management.
5. CI/CD & GitHub Actions: Workflow inspection, workflow runs, job status, build artifacts (list_workflow_run_artifacts, get_workflow_run_artifact), log tailing, run cancel/retry, and action triggers.
6. Releases & Tags: Release publishing, tag creation, asset inspection, and release notes management.
7. Actions Variables & Secrets: Manage repository and environment variables for automated CI/CD pipelines.
8. Collaborators & Permissions: Audit and manage repository collaborators and permission levels.
9. Security & Dependabot: Audit Dependabot security alerts and vulnerability reports.
10. Gists & Snippets: Full gist lifecycle for sharing code templates and configurations.
11. Webhooks & Integrations: Audit repository webhooks and subscribed event triggers.

---

Quickstart & Installation

Option 1: Run with npx (No installation needed)

npx -y @sumirati/mcp-github

Option 2: Install Globally

npm install -g @sumirati/mcp-github
mcp-github

Option 3: Local Clone

git clone https://github.com/sumirati/mcp-github.git
cd mcp-github
npm install
npm test
npm start

---

Environment Configuration

---

Client Configuration

Google Antigravity / Claude Desktop / Cursor

Add to your MCP configuration file (mcp_config.json or claude_desktop_config.json):

Using npm / npx (Recommended):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@sumirati/mcp-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<your-github-token>",
        "GITHUB_READ_ONLY": "false"
      }
    }
  }
}

Using local clone:

{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["/path/to/mcp-github/index.js"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<your-github-token>",
        "GITHUB_READ_ONLY": "false"
      }
    }
  }
}

---

Complete Action Catalog Reference (75 Actions)

All 75 actions feature strict input validation and 2-tier field-mask projections:

1. The 5 Client-Exposed Tools (Hybrid Mode)

2. Repositories & Branches (11 actions)

3. Commits & Statuses (4 actions)

4. Pull Requests & Reviews (11 actions)

5. Issues & Labels (8 actions)

6. Milestones (4 actions)

7. Collaborators & Roles (4 actions)

8. Actions Variables & Secrets (6 actions)

9. GitHub Actions & CI (8 actions)

10. Releases & Git Tags (5 actions)

11. Webhooks, Gists, Security & User Context (18 actions)

• Webhooks & Topics (4 actions): list_repository_topics, set_repository_topics, list_webhooks, create_webhook.
• Gists (5 actions): list_gists, get_gist, create_gist, update_gist, delete_gist.
• Security (1 action): list_dependabot_alerts.
• User & Orgs (4 actions): get_authenticated_user, get_user, list_user_organizations, list_accessible_repositories.

---

Token Economy & Output Projection Filters

Raw GitHub REST API responses are notoriously heavy (often 30KB–100KB per Issue or PR). @sumirati/mcp-github enforces strict token economy:

• System Prompt Tax Reduction (>93% savings): Shrinks MCP tool definition footprint from ~14.7k tokens down to ~450 tokens.
• Recursive Output Projection Filter (projectOutput): Automatically strips redundant metadata fields (_links, avatar_url, gravatar_id, node_id, site_admin, user navigation URLs, internal API links, and null/empty fields) before payloads reach the LLM, guaranteeing 70%+ output token savings.
• Unified Diff Truncation: PR and commit diffs are capped by line count (max_diff_lines, default: 400).
• Safe Log Tailing: CI workflow job logs extract the failure tail (tail_lines, default: 200) instead of megabyte log dumps.

---

Acknowledgements & Lineage

This project incorporates architectural concepts, schemas, and patterns from:

• @modelcontextprotocol/sdk (MIT License) — Copyright (c) Anthropic, PBC.
• zod (MIT License) — Colin McDonnell.
• GitHub REST API Specifications — GitHub, Inc.
• jmrplens/gitlab-mcp-server — Dynamic action discovery and meta-dispatcher pattern concepts.
• @sumirati/mcp-gitlab — Sibling project architecture, 3-tier read-only mode, and token projection standards.

See NOTICE for complete third-party attribution details.

---

License

This project is licensed under the MIT License — Copyright (c) 2026 sumirati@buggycode.net.