github-mcp-bridge

A lightweight TypeScript MCP server for GitHub. It exposes GitHub operations as MCP tools over HTTP while keeping GitHub credentials server-side.

Quick Start

1. Install dependencies

npm install

2. Create local configuration

Copy the example environment file:

cp .env.example .env

3. Create your connector token

CONNECTOR_SECRET is a secret token that you generate yourself. It has two purposes:

• You add it to your local .env file and to your Vercel project environment variables.

• Your MCP client sends it when connecting to the bridge, using either an Authorization: Bearer header or an X-Api-Key header.

It is not supplied by GitHub, Vercel, or Upstash Redis.

Generate a token:

openssl rand -hex 64

Copy the generated value into .env with your GitHub token:

# Required for local development
GITHUB_PAT=ghp_xxx
CONNECTOR_SECRET=your-generated-token

# Optional
PORT=3000

Keep both values private. GITHUB_PAT authenticates the bridge to GitHub. CONNECTOR_SECRET authenticates an MCP client to your local or Vercel-hosted bridge.

4. Start the server

npm run dev

The local server listens on http://localhost:3000 by default.

Related MCP server: epik-gh

Environment Variables

Owner-specific token selection falls back to GITHUB_PAT when no matching GITHUB_PAT_<OWNER> variable is configured.

Deployment

1. Create a Vercel project

Import this repository into Vercel and configure the production branch.

2. Add Upstash Redis

In the Vercel project, open Storage, add Upstash Redis, and connect it to the project.

The Vercel integration supplies the Upstash Redis connection variables automatically. Do not copy Redis credentials into .env, GitHub Actions, or MCP client configuration.

3. Add Vercel environment variables

Add these variables in Vercel → Project → Settings → Environment Variables:

GITHUB_PAT
CONNECTOR_SECRET

Use your GitHub Personal Access Token as GITHUB_PAT.

Generate CONNECTOR_SECRET locally:

openssl rand -hex 64

Add the generated value to Vercel as CONNECTOR_SECRET. This exact value becomes the token required by every MCP client connecting to your hosted bridge.

4. Deploy

Push the branch to GitHub or deploy from the Vercel dashboard.

The deployment uses Upstash Redis for session continuity across Vercel’s serverless instances. Local development and CI use in-memory sessions and do not contact Redis.

Sessions

Sessions are bound to the authenticated caller; they provide request continuity and do not replace authentication.

• Sessions expire after 2 hours without a valid request.

• Sessions cannot live longer than 12 hours from creation.

• Each valid request refreshes the idle window without extending the maximum lifetime.

• initialize, notifications/initialized, and ping are supported.

• The server can maintain session continuity without requiring every client to manage an Mcp-Session-Id header manually.

Available Tools

The bridge currently exposes 37 tools. Call tools/list to obtain the authoritative tool definitions and input schemas at runtime.

Repositories

Branches

Files

Pull Requests

Issues

Commits

Actions

Search

Tool Requests

All repository-scoped tools require owner and repo. list_repositories is the exception because it lists repositories available to the configured token.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_branches",
    "arguments": {
      "owner": "SamNewhouse",
      "repo": "github-mcp-bridge"
    }
  }
}

Connecting an MCP Client

Use your local server URL or Vercel deployment URL as the MCP endpoint.

Authenticate every request with the same CONNECTOR_SECRET value that you added to .env locally or to Vercel in production.

Authorization: Bearer <CONNECTOR_SECRET>

Alternatively:

X-Api-Key: <CONNECTOR_SECRET>

For example, if Vercel contains:

CONNECTOR_SECRET=abc123...

your MCP client must send:

Authorization: Bearer abc123...

The bridge validates the connector token using timing-safe comparison and rate-limits repeated failed authentication attempts.

Testing

npm test
npm run test:unit
npm run test:integration
npm run typecheck

The project currently has 19 test suites and 238 passing tests.

Scripts

Security

• Keep GITHUB_PAT server-side only.

• Do not expose Upstash Redis credentials to MCP clients.

• Do not commit .env files, GitHub tokens, Redis credentials, or CONNECTOR_SECRET.

• Use the minimum GitHub PAT permissions required.

• Rotate CONNECTOR_SECRET and GITHUB_PAT immediately if either is exposed.

License

MIT