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.

@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 23,112 tokens (92,447 B) down to 1,125 tokens (4,498 B) (95.1% 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 83 actions across 13 domains is accessible on-demand via dynamic action discovery (github_find_actions $\rightarrow$ github_execute_action), delivering 91%–99% token savings with default high-density Markdown tables and summaries (format: "markdown" | "json").
• 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 (5-Tool Hybrid Surface):
├── 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):
└── 83 Curated Actions across 13 Domains (grounded in GitHub REST API 2022-11-28)

Core Capabilities Across 13 Domains

1. Repositories & Branch Governance (repositories, 12 actions): Full repository lifecycle, branch management, branch protection rules (get_branch_protection), file reading (auto Base64-decoded, symbol outlines, line slicing), single-file commits, and forks.
2. Commits & Commit Statuses (commits, 6 actions): Commit history, token-capped commit diffs (get_commit), atomic multi-file commits via Git Trees API (create_commit, push_files), and commit status checks.
3. Pull Requests & Code Reviews (pull-requests, 11 actions): PR lifecycle (create, update, merge), review comments, inline diff reviews, and unified diff inspection with lockfile filtering.
4. Issues & Labels (issues, 8 actions): Issue tracking, upstream indexed filtering, conversation comments, and label management.
5. Project Milestones (milestones, 4 actions): Milestone creation, progress tracking, and deadline management.
6. Collaborators & Permissions (collaborators, 4 actions): Audit and manage repository collaborators and permission levels.
7. Actions Variables & Secrets (variables, 6 actions): Manage repository Actions configuration variables and inspect secret metadata.
8. Gists & Code Snippets (gists, 5 actions): Full gist lifecycle for sharing multi-file code snippets and configurations.
9. GitHub Actions & CI/CD (actions, 10 actions): Workflow inspection, workflow runs, job step breakdown, build artifacts (list_workflow_run_artifacts, get_workflow_run_artifact), smart failure log extraction (get_job_logs), run cancel/rerun, and manual workflow dispatch.
10. Releases & Git Tags (releases, 5 actions): Release publishing, lightweight/annotated tag creation, and release asset inspection.
11. User, Organizations, Teams & Diagnostics (user, 7 actions): Authenticated user identity, organization inspection, team creation (create_team), accessible repositories, and API health/rate-limit diagnostics (system_health_check).
12. Webhooks & Repository Topics (webhooks, 4 actions): Audit repository event webhooks and manage repository topic tags.
13. Security & Dependabot (security, 1 action): Audit Dependabot vulnerability alerts by state and severity.

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 (83 Actions)

All 83 actions feature strict Zod input validation and 2-tier output projection:

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

2. Repositories & Branches (repositories — 12 actions)

3. Git Commits & Statuses (commits — 6 actions)

4. Pull Requests & Code Reviews (pull-requests — 11 actions)

5. Issues & Labels (issues — 8 actions)

6. Project Milestones (milestones — 4 actions)

7. Collaborators & Roles (collaborators — 4 actions)

8. Actions Variables & Secrets (variables — 6 actions)

9. Gists & Code Snippets (gists — 5 actions)

10. GitHub Actions & CI/CD Observability (actions — 10 actions)

11. Releases & Git Tags (releases — 5 actions)

12. User, Organizations & Teams (user — 7 actions)

13. Webhooks & Topics (webhooks — 4 actions)

14. Security & Dependabot (security — 1 action)

Benchmarks: Reproducible Token Economy Proof (test/benchmark-test.js)

Grounded strictly in official GitHub REST API (2022-11-28) response schemas (test/fixtures/github-api-v3-fixtures.js) and verified on every npm test run via node test/benchmark-test.js:

How Token Compression Works

• System Prompt Tax Reduction (95.1% savings): Shrinks MCP ListTools schema footprint from 83 full tool schemas (23,112 tokens / 92,447 B) down to the 5-tool hybrid surface (1,125 tokens / 4,498 B).
• Recursive Output Projection Filter (projectOutput): Automatically strips GitHub REST API v3 hypermedia template URLs (*_url RFC 6570 templates), avatar_url, gravatar_id, node_id, site_admin, _links, internal api.github.com self-links, and null/"" fields.
• Smart Diff & Lockfile Truncation: Commit and PR diffs automatically collapse dependency lockfiles (package-lock.json, pnpm-lock.yaml, yarn.lock, go.sum, Cargo.lock, *.min.js) via ignore_lockfiles: true by default. Pass ignore_lockfiles: false to inspect full lockfile diffs.
• Conservative Default Pagination: All list actions default to per_page: 10 (max: 100).
• Default High-Density Markdown Format: Discovery (github_find_actions), execution (github_execute_action), and all 3 eager tools default to format: "markdown".
• Unified Diff Truncation: PR (max_lines) and commit (max_diff_lines) diffs default to 400 lines.
• Safe Log Tailing: CI workflow job logs extract the failure block and teardown tail (tail_lines, default: 100) with ANSI escape sequence stripping.

Roadmap

Completed in v2.1

• [x] Upstream indexed filtering & strict pagination caps (state, labels, assignee, creator, mentioned, milestone, since)
• [x] Client error resilience (Secondary rate limit / abuse detection, 403/404 scope diagnostics, empty-body 201/202 handling)
• [x] Hardened output projection with recursion depth guard (maxDepth = 32), RFC 6570 hypermedia URL stripping, and empty collection preservation
• [x] Nested child team & organization management (create_team, get_organization)
• [x] Smart CI/CD failure log extraction & ANSI sequence stripping in get_job_logs (strip_ansi, smart_failure)
• [x] Outline-first code symbol extraction & line range slicing in get_file_contents (outline_only, start_line, end_line)
• [x] Atomic multi-file commits (create_commit, push_files) supporting file creation, updates, and deletions via GitHub Git Trees API
• [ ] Pre-flight mergeability & conflict verification (get_mergeability)
• [ ] Token scope self-auditing & permission pre-flight

Future Horizons (v2.x)

• [ ] Standardized collection _summary headers to facilitate multi-turn history pruning in LiteLLM / Eigent agent orchestration
• [ ] Remote Transports: Streamable SSE and HTTP remote server modes
• [ ] Scoped GraphQL query engine for relational deep inspections
• [ ] DevSecOps code scanning & secret scanning alert queries
• [ ] Scoped & rate-guarded code search within project repositories

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.