github-mcp-server

Translates Model Context Protocol (MCP) CallToolRequest messages from AI clients (VS Code, Claude Desktop, Cursor) into GitHub REST/GraphQL API calls, executing operations and returning structured CallToolResult responses. Implements stdio/JSON-RPC for local deployment and HTTP for remote GitHub-hosted service at api.githubcopilot.com/mcp/, handling bidirectional protocol conversion with full request/response marshaling.

Organizes 162+ GitHub tools into logical toolsets (context, repos, issues, pull_requests, users, search, code_security, actions, projects) with runtime configuration to selectively enable/disable groups. Implements AllTools() registry pattern that returns tool metadata with descriptions and parameter schemas, allowing MCP clients to discover and expose only relevant capabilities. Supports special keywords: 'all' (enable everything), 'default' (context, repos, issues, pull_requests, users), and 'dynamic' (runtime discovery).

Supports local deployment (Docker container or binary with stdio/JSON-RPC transport) and remote deployment (GitHub-hosted HTTP service at api.githubcopilot.com/mcp/). Abstracts transport layer so same tool implementations work with both stdio and HTTP. Local deployment uses Personal Access Token authentication, remote uses OAuth. Implements graceful shutdown and signal handling for local deployments.

Implements 'dynamic' keyword that enables runtime toolset discovery, allowing MCP clients to query available tools based on server configuration and token permissions. Discovers toolsets at server startup and exposes metadata (name, description, tools) through MCP ListTools protocol. Supports conditional toolset availability based on token scopes and organization membership. Reduces context size by only exposing relevant capabilities.

Integrates GitHub GraphQL API (v4) for queries requiring multiple data relationships (e.g., repository with issues, PRs, and collaborators in single query). Implements query optimization to reduce round-trips and API costs. Handles GraphQL-specific features: aliases for parallel queries, fragments for reusable query components, and pagination with cursors. Falls back to REST API for simple operations to minimize complexity.

Supports configuration through environment variables and YAML/JSON config files specifying enabled toolsets, security mode, authentication method, and server settings. Implements configuration precedence (CLI flags > env vars > config file > defaults). Validates configuration at startup and provides clear error messages for invalid settings. Supports hot-reload for some settings without server restart.

Executes repository-level operations (list repos, get repo details, search repositories, manage branches, create/update files) by routing requests through GitHub REST API v3 and GraphQL API v4. Implements dual-API strategy where REST handles simple CRUD operations and GraphQL handles complex queries requiring multiple data relationships. Manages authentication context per request and handles pagination for large result sets.

Manages GitHub issues and pull requests through create, read, update, and search operations. Implements issue/PR state transitions (open, closed, draft, ready for review), label management, assignee handling, and comment threading. Uses REST API for standard CRUD and GraphQL for complex queries involving multiple PRs/issues with relationships. Handles pagination and filtering by state, labels, assignees, and date ranges.

Searches repository code using GitHub's code search API with support for language-specific queries, file patterns, and symbol matching. Implements search parameter validation and result ranking by relevance. Integrates with code security toolset to identify vulnerabilities, secrets, and dependency issues. Returns code snippets with file paths, line numbers, and context for analysis by AI agents.

Manages GitHub Actions workflows through tool calls that trigger workflow runs, retrieve run status and logs, and manage workflow artifacts. Implements workflow dispatch with input parameters, run querying by status (queued, in_progress, completed), and log streaming. Handles workflow file discovery and validation. Supports both push-triggered and manual dispatch workflows.

Manages GitHub Projects (v2 API) including board creation, column/field management, and card operations. Implements issue-to-project linking, status transitions through custom fields, and bulk card updates. Uses GraphQL API for complex project queries involving multiple issues and relationships. Supports both classic Projects (v1) and new Projects (v2) with different field types (single_select, number, date, text).

Discovers authenticated user identity, team memberships, and organization roles through GitHub API. Implements permission inference by querying repository access levels and team permissions. Returns user profile data (login, name, email, avatar), team memberships with roles, and organization affiliations. Caches context to reduce API calls for repeated permission checks.

Validates all tool parameters against JSON schemas before executing GitHub API calls. Implements type checking (string, number, boolean, array), required field validation, and enum constraint enforcement for parameters like state (open/closed) and role (admin/member). Returns detailed error messages with parameter hints when validation fails. Prevents malformed API requests and provides early feedback to MCP clients.

Implements security modes that restrict tool capabilities based on configuration: read-only mode disables all write operations (create, update, delete), and lockdown mode further restricts to specific safe operations. Validates GitHub token scopes at server startup and prevents operations requiring unavailable scopes. Logs all tool executions for audit trails. Supports per-toolset permission control through configuration.