If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/github/github-mcp-server shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 24+ active contributors
• Distributed ownership (top contributor 17% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live github/github-mcp-server repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/github/github-mcp-server.

What it runs against: a local clone of github/github-mcp-server — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in github/github-mcp-server | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of github/github-mcp-server. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/github/github-mcp-server.git
#   cd github-mcp-server
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of github/github-mcp-server and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "github/github-mcp-server(\\.git)?\\b" \\
  && ok "origin remote is github/github-mcp-server" \\
  || miss "origin remote is not github/github-mcp-server (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "cmd/github-mcp-server/main.go" \\
  && ok "cmd/github-mcp-server/main.go" \\
  || miss "missing critical file: cmd/github-mcp-server/main.go"
test -f "internal/ghmcp/server.go" \\
  && ok "internal/ghmcp/server.go" \\
  || miss "missing critical file: internal/ghmcp/server.go"
test -f "go.mod" \\
  && ok "go.mod" \\
  || miss "missing critical file: go.mod"
test -f "pkg/github" \\
  && ok "pkg/github" \\
  || miss "missing critical file: pkg/github"
test -f "docs/server-configuration.md" \\
  && ok "docs/server-configuration.md" \\
  || miss "missing critical file: docs/server-configuration.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/github/github-mcp-server"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

GitHub MCP Server is GitHub's official Model Context Protocol (MCP) server that connects AI agents, assistants, and chatbots directly to GitHub's API and capabilities. It enables AI tools to natively read repositories, manage issues and PRs, analyze code, monitor CI/CD workflows, and automate GitHub actions through natural language—built in Go with remote HTTP deployment and local CLI modes. Single binary Go application: cmd/github-mcp-server/ contains main.go (entry point), helpers.go (utilities), generate_docs.go, and list_scopes.go for documentation and auth introspection. cmd/mcpcurl/ provides an HTTP testing utility. Docs/ directory has installation guides for VS Code, Claude, Cline, Windsurf, and feature documentation. Containerized via Dockerfile for remote deployment.

AI developers and DevOps engineers who want to integrate GitHub context into AI agents (Claude, VS Code Copilot, Cursor, Windsurf) for automating repository management, code analysis, issue triage, PR workflows, and CI/CD intelligence without writing custom GitHub API integrations.

Production-ready and actively maintained by GitHub. The codebase is substantial (1.9MB of Go), has multiple CI workflows (.github/workflows/), Docker deployment (Dockerfile, docker-publish.yml), and formal governance (SECURITY.md, CODE_OF_CONDUCT.md). Go module targets v1.25.0 with stable dependencies (google/go-github v82, modelcontextprotocol/go-sdk v1.5.1).

Low risk for an official GitHub project. Dependencies are well-maintained (Google, Modelcontextprotocol org). However, MCP adoption is still early-stage, and tight coupling to GitHub's API means breaking changes upstream could impact the server. Requires auth tokens with GitHub scope management (see list_scopes.go), so token leakage is a realistic concern.

Active development visible in multiple CI workflows: go.yml (testing), lint.yml (linting via golangci), goreleaser.yml (release automation), docker-publish.yml (container builds). Recent additions include insiders-features.md, go-sdk-tool-migrator.md agent, and copilot-instructions.md suggesting ongoing AI integration improvements. Registry-releaser.yml indicates MCP registry publication.

git clone https://github.com/github/github-mcp-server.git && cd github-mcp-server && go mod download && go build ./cmd/github-mcp-server. Requires Go 1.25.0+. For local testing: ./github-mcp-server --help. For Docker: docker build -t github-mcp-server . && docker run -e GITHUB_TOKEN=<token> github-mcp-server.

Daily commands: Local dev: go run ./cmd/github-mcp-server/main.go (defaults to stdio or HTTP based on env). For HTTP server mode: set MCP_SERVER_ADDRESS=localhost:8080 and run the binary. Docker: docker-compose or docker run with GITHUB_TOKEN env var. See docs/installation-guides/ for host-specific setup (VS Code, Claude, Cline, Windsurf).

• cmd/github-mcp-server/main.go — Entry point that initializes the MCP server, handles CLI configuration, and starts the GitHub integration.
• internal/ghmcp/server.go — Core server implementation that defines all MCP tools, resources, and the request/response handling loop for GitHub operations.
• go.mod — Declares all dependencies including the MCP SDK and GitHub client libraries that form the foundation of this server.
• pkg/github — Root package containing all GitHub API tool implementations that contributors must understand to add new features.
• docs/server-configuration.md — Documents configuration options, environment variables, and authentication setup required to run the server.
• .github/workflows/go.yml — CI/CD pipeline that enforces build, test, and lint standards for all contributions.
• README.md — High-level overview of the GitHub MCP Server, its use cases, and setup instructions for developers.

Add a new GitHub API tool

1. Define the tool handler function in a new file under pkg/github/ (e.g., pkg/github/my_new_tool.go) that takes *github.Client and returns structured output (pkg/github/my_new_tool.go)
2. Register the tool in internal/ghmcp/server.go by adding a new entry to the tools map with InputSchema and handler callback (internal/ghmcp/server.go)
3. Add snapshot tests in pkg/github/toolsnaps/ to validate the tool's output matches expected schema (internal/toolsnaps/toolsnaps_test.go)
4. Document the tool's purpose, inputs, and outputs in docs/ and regenerate docs via cmd/github-mcp-server/generate_docs.go (cmd/github-mcp-server/generate_docs.go)

Add a new GraphQL query capability

1. Add the GraphQL query type definition to pkg/context/graphql_features.go to detect if the GitHub instance supports it (pkg/context/graphql_features.go)
2. Create the query implementation in pkg/github/ using the shurcooL/githubv4 client (pkg/github)
3. Add mock responses to internal/githubv4mock/githubv4mock.go so tests work offline (internal/githubv4mock/githubv4mock.go)
4. Write integration tests in e2e/e2e_test.go to validate against real GitHub API (e2e/e2e_test.go)

Add request-level configuration or context

1. Define new context fields in pkg/context/request.go to capture request metadata (pkg/context/request.go)
2. Extract and validate the new context from incoming MCP requests in pkg/context/token.go or a new context file (pkg/context/token.go)
3. Update internal/ghmcp/server.go to populate the context before calling tool handlers (internal/ghmcp/server.go)
4. Document the new configuration option in docs/server-configuration.md (docs/server-configuration.md)

Add installation guide for a new AI platform

1. Create a new markdown file under docs/installation-guides/ (e.g., install-my-platform.md) with setup steps (docs/installation-guides/install-my-platform.md)
2. Reference the new guide in docs/installation-guides/README.md (docs/installation-guides/README.md)
3. If the platform uses a manifest (like Gemini), create platform-extension.json with tool definitions (gemini-extension.json)

• Go + goroutines — Efficient concurrent handling of multiple AI client connections and GitHub API requests with minimal resource overhead
• Model Context Protocol (MCP) SDK — Standardized interface allowing the server to work with any MCP-compatible AI client (Claude, Copilot, Cursor, etc.)
• shurcooL/githubv4 (GraphQL client) — Type-safe GraphQL queries for GitHub's modern API, more flexible than REST API for complex data requirements
• cache2go in-memory caching — Low-latency response caching for frequently accessed GitHub data without external dependencies
• Docker + goreleaser — Cross-platform binary distribution and containerized deployment for various hosting environments
• Cobra CLI framework — Extensible command structure for server modes, documentation generation, and scope listing utilities

• In-memory caching (cache2go) instead of Redis

  • Why: Simplifies deployment—no external service required; acceptable for single-instance servers
  • Consequence: Cache is lost on server restart; not suitable for horizontally scaled deployments; single-machine memory limits

• GraphQL-first API access over REST

  • Why: More efficient batching of related queries; strongly typed schema; better for complex nested data
  • Consequence: Requires understanding GraphQL; not all GitHub features available via GraphQL; slightly steeper learning curve

• Snapshot testing instead of golden files

  • Why: Embedded test data makes tests portable and self-contained; easy to review diffs
  • Consequence: Large snapshot files; diffs can be noisy; less suitable for very large response bodies

• Single MCP server process serving all clients

  • Why: Simplicity; minimal operational complexity for most use cases
  • Consequence: No request isolation; one misbehaving client can affect others; poor scaling for many concurrent users

• Does not implement GitHub authentication—relies on client to provide valid GitHub token
• Does not provide real-time webhooks or streaming updates from GitHub
• Does not store persistent state or manage long-running workflows beyond single API calls
• Not designed for high-concurrency distributed deployments (no distributed caching, no request sharding)
• Does not provide UI or web dashboard—MCP-only interface

GITHUB_TOKEN environment variable is required for any GitHub API calls; without it, the server cannot authenticate and all tools will fail. MCP protocol version mismatch can cause incompatibility—check modelcontextprotocol/go-sdk version compatibility with your host (VS Code 1.101+, Claude Desktop, Cursor, etc.). GitHub API rate limits (5000 reqs/hour for authenticated users) are not explicitly surfaced but can silently fail if exceeded. The remote server at https://api.githubcopilot.com/mcp/ is a separate hosted instance; local mode requires different authentication flow. Policies and governance (docs/policies-and-governance.md) may restrict certain operations depending on GitHub organization settings.

• Model Context Protocol (MCP) — Core protocol enabling bidirectional communication between AI hosts and servers; understanding MCP is essential for adding new tools and resources
• OAuth 2.0 scopes and permissions — GitHub's granular permission model requires careful scope management; list_scopes.go exists because MCP servers must declare what permissions they need
• GraphQL vs REST API trade-offs — This server uses both shurcooL/graphql and google/go-github; choosing between them impacts query efficiency and rate limit consumption
• Server-Sent Events (SSE) and stdio transport — MCP supports both HTTP and stdio transports for different deployment contexts (remote vs local); affects how the server initializes and communicates
• JSON Schema validation — google/jsonschema-go is used to validate tool inputs and outputs; ensures MCP clients receive well-formed requests and responses
• Rate limiting and caching strategies — muesli/cache2go is included for caching; critical for managing GitHub's rate limits when serving many AI queries
• Container orchestration and registry federation — docker-publish.yml and registry-releaser.yml automate container builds and MCP registry registration; essential for understanding deployment pipeline

• modelcontextprotocol/python-sdk — Official Python reference SDK for MCP protocol; useful for understanding MCP semantics independent of GitHub
• modelcontextprotocol/server-template — Official MCP server template showing boilerplate for other Go-based MCP servers; reference architecture
• google/go-github — Official Go GitHub API client library used by this project; understanding it is essential for extending tool capabilities
• github/copilot-cli — Another GitHub official project integrating AI with GitHub; demonstrates complementary CLI-based AI automation patterns
• AntonioErdeljac/github-copilot-java-plugin — Community example of extending GitHub Copilot with language-specific tools; shows alternative integration approaches

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive e2e tests for core MCP tools and GitHub API interactions

The repo has an e2e directory with only a README and single test file (e2e_test.go), but given the complexity of GitHub API integration and multiple installation paths (Claude, Cline, Cursor, etc.), there's a significant gap in end-to-end test coverage. This would validate that all MCP tools work correctly across different client configurations and GitHub API scenarios.

• [ ] Expand e2e/e2e_test.go with test cases for core tools: issue creation, PR operations, code search, and workflow monitoring
• [ ] Add test fixtures in e2e/ directory for mock GitHub responses
• [ ] Create e2e test scenarios for different auth/scope configurations referenced in docs/scope-filtering.md
• [ ] Add CI step to .github/workflows/go.yml to run e2e tests against test repository

Add missing workflow for testing MCP schema validation and compatibility

The repo has .github/workflows/mcp-diff.yml but no dedicated workflow to validate that the MCP schema generation (referenced in cmd/github-mcp-server/generate_docs.go) doesn't break compatibility with MCP clients. This is critical since multiple installation guides exist but schema regressions could silently break integrations.

• [ ] Create .github/workflows/schema-validation.yml to run cmd/github-mcp-server/generate_docs.go
• [ ] Add schema comparison step to detect breaking changes in tool definitions
• [ ] Validate generated schema against MCP Go SDK version in go.mod (currently v1.5.1-0.20260403154220-27f29c1cef3b)
• [ ] Include schema validation in pull_request_template.md checklist

Add integration tests for remote server deployment scenarios

The repo has docs/remote-server.md explaining remote deployment but no tests validating the remote server setup works correctly. Given that the Dockerfile and docker-publish.yml workflow exist, there's an opportunity to add tests ensuring the containerized server functions properly with various GitHub token configurations.

• [ ] Create new test file cmd/github-mcp-server/remote_server_test.go for HTTP server validation
• [ ] Add integration test cases for host-integration scenarios documented in docs/host-integration.md
• [ ] Test authentication flows with different token scopes (referenced in cmd/github-mcp-server/list_scopes.go)
• [ ] Add Docker-based integration test step to .github/workflows/docker-publish.yml to validate the published image

• Add unit tests for cmd/github-mcp-server/helpers.go—currently no visible test coverage shown in the file list despite being a utility layer used by main.go; would improve reliability.
• Expand docs/error-handling.md with concrete examples of GitHub API errors (rate limits, 404s, permission denied) and how the MCP server surfaces them to clients—currently minimal error documentation exists.
• Create a CHANGELOG.md or release notes template in docs/ documenting MCP tool/resource additions and breaking changes per release; .goreleaser.yaml suggests automation-ready infrastructure.

• High · Outdated Go Version with Known Vulnerabilities — go.mod, Dockerfile (golang:1.25.9-alpine). The project specifies Go 1.25.0 in go.mod, but the Dockerfile uses Go 1.25.9-alpine. Go 1.25.0 may contain known security vulnerabilities that were patched in later 1.25.x releases. Additionally, Go 1.25.x itself may have reached or be approaching end-of-life status. Fix: Regularly update to the latest stable Go version. Consider using Go 1.26 or later if available. Ensure CI/CD pipeline enforces dependency scanning for all Go modules.
• High · Dependency on Pre-release MCP SDK — go.mod - modelcontextprotocol/go-sdk dependency. The project depends on github.com/modelcontextprotocol/go-sdk v1.5.1-0.20260403154220-27f29c1cef3b, which is a pre-release/development version (indicated by the commit hash). Pre-release versions may contain unreviewed code, incomplete security patches, and unstable APIs. Fix: Upgrade to the latest stable release of the MCP SDK once available. If a stable version exists, migrate immediately. Implement automated dependency update checks in CI/CD.
• High · Missing SBOM and Supply Chain Security — Repository root, .github/workflows/. No evidence of Software Bill of Materials (SBOM) generation or supply chain security verification. The project handles GitHub authentication and API tokens but lacks documented supply chain security practices. Fix: Implement SBOM generation in CI/CD pipeline using tools like syft or cyclonedx. Add software supply chain security scanning and verification steps. Document dependency pinning and verification procedures.
• Medium · Potential XSS Vulnerability via HTML Sanitization — Dependency: github.com/microcosm-cc/bluemonday v1.0.27. The project includes microcosm-cc/bluemonday (HTML sanitization library), suggesting HTML content is being processed. If sanitization is not applied consistently across all user-controlled content rendering, XSS vulnerabilities could exist. Fix: Audit all code paths that render HTML content. Ensure bluemonday or equivalent sanitization is applied to all user-controlled content before rendering. Add security tests for XSS prevention.
• Medium · Unvalidated OAuth2 Token Handling — Dependencies: golang.org/x/oauth2, github.com/google/go-github. The project uses github.com/google/go-github for GitHub API access, which requires OAuth2 tokens (golang.org/x/oauth2 v0.35.0). No visible token validation, rotation, or secure storage mechanisms documented in the provided codebase structure. Fix: Implement token validation and rotation mechanisms. Use secure token storage (encrypted at rest). Add token expiration checks. Document token handling security in SECURITY.md.
• Medium · Missing Security Headers Configuration — cmd/github-mcp-server/, Dockerfile. The project uses go-chi/chi v5 web framework, but no evidence of security middleware (HSTS, CSP, X-Frame-Options, etc.) is visible in the provided file structure. Fix: Implement security middleware in chi router initialization. Add HSTS, Content-Security-Policy, X-Frame-Options, X-Content-Type-Options headers. Reference: OWASP Secure Headers Project.
• Medium · Docker Image Base Layer Pinning Without Verification — Dockerfile - FROM statements. While Dockerfile pins node and Go Alpine images to specific SHAs, there is no verification that these images come from trusted registries or GPG signature validation. Fix: Use image signature verification with cosign or similar tools. Verify image provenance. Consider using minimal base images (scratch or distroless). Implement container scanning in CI/CD pipeline.
• Medium · Incomplete Dependency Pinning in Indirect Dependencies — undefined. Several indirect dependencies lack explicit version pins or use very old versions (e.g., github.com/shurcooL/githubv4 pinned to 0.0.0-20240727, muesli/cache2go pinned to 0.0 Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.