GitHub MCP Server

MCP server in Node.js and TypeScript that allows a compatible agent to execute operations on GitHub using natural language.

Architecture

Usuario -> Antigravity (Host) -> MCP Client -> MCP Server -> Octokit -> GitHub API

A chatbot mainly maintains a conversation. An AI assistant helps using additional capabilities. An AI Agent interprets a goal, decides what actions it needs, and uses tools to achieve it.

MCP (Model Context Protocol) standardizes communication between an AI Host, an MCP client, and servers that expose tools or data sources. In this project the transport is stdio: protocol messages use stdin/stdout and logs use stderr.

Related MCP server: GitHub MCP Server

Technologies

• Node.js 18 or higher

• TypeScript with strict: true

• @modelcontextprotocol/sdk

• @octokit/rest

• zod

• dotenv

• Vitest

Installation

npm install
npm run build

Configuration

Copy .env.example as .env and fill in the token locally:

GITHUB_TOKEN=tu_token_de_github

.env is excluded by .gitignore and should never be committed.

The token should only have the necessary permissions. For private repositories, fine-grained tokens should allow access to the repository and contents/issues depending on the operation. A classic PAT may require repo. The user permission is only needed for additional user operations, and admin:org is not needed for the current five tools unless that scenario is required. Tokens are not included in examples, tests, logs, or MCP responses.

Scripts

npm run dev       # Ejecuta TypeScript directamente
npm run build     # Compila a dist/
npm start         # Ejecuta el JavaScript compilado
npm test          # Ejecuta los tests unitarios

MCP Tools

create_repository

Creates a new repository in the authenticated account.

Inputs: name, description.

Returns the full name and URL of the repository.

create_issue

Creates an issue in an existing repository.

Inputs: owner, repo, title, body.

Returns the issue number, title, and URL.

list_repositories

Lists the repositories of the authenticated user.

Optional inputs: page, per_page.

Returns a summarized list with full name and URL.

create_commit

Creates or updates a file and generates the commit using the Contents API.

Inputs: owner, repo, path, message, content; branch is optional.

The tool first queries the file. If it exists, it uses its SHA; if GitHub responds with 404, it creates the file without a SHA.

list_issues

Lists the open issues of a repository and excludes pull requests.

Inputs: owner, repo; page and per_page are optional.

Error Handling

Errors are classified as ValidationError, AuthenticationError, GitHubAPIError, or NetworkError. MCP responses contain actionable messages and do not forward technical messages that could expose credentials.

Operations retry up to three times only on rate limiting, 5xx errors, or recoverable network errors. Validation, authentication, and missing resource errors are not retried.

Tests

Tests do not call real GitHub. They use mocked Octokit clients and cover:

• Valid and invalid schemas for repositories and issues.

• Creation of repositories and issues.

• Listing of repositories and open issues.

• Creation of new files.

• Updating existing files using SHA.

• Error transformation.

• Retry with backoff.

Run npm test to run the full suite.

MCP Inspector

Build the project and run the server using the Inspector:

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

Set GITHUB_TOKEN in the environment before starting the Inspector. Verify that the five tools, their descriptions, and schemas appear. For a real test, use a test repository and avoid destructive operations.

Antigravity and VS Code

The file .vscode/mcp.json contains a stdio configuration without versioned credentials. Run npm run build before starting the server from the Host. The configuration runs dist/index.js and takes GITHUB_TOKEN from the local environment.

For another MCP-compatible Host, register the equivalent command:

{
  "type": "stdio",
  "command": "node",
  "args": ["dist/index.js"],
  "env": { "GITHUB_TOKEN": "${env:GITHUB_TOKEN}" }
}

Make sure the Host detects create_repository, create_issue, list_repositories, create_commit, and list_issues.

Structure

src/
  errors/       Errores clasificados y sanitizacion
  github/       Cliente Octokit y operaciones GitHub
  schemas/      Schemas Zod y tipos inferidos
  tools/        Handlers MCP individuales
  utils/        Retry, logging, respuestas y ensamblado del servidor
  index.ts      Entrada y transporte stdio
tests/          Tests unitarios con mocks

Security

• Do not hardcode tokens.

• Do not commit .env.

• Do not print tokens or authorization headers.

• Keep logs on stderr to avoid contaminating the protocol.

• Apply the principle of least privilege to the PAT.

• Review changes before executing tools that write to GitHub.