github-mcp-bridge

A lightweight TypeScript MCP (Model Context Protocol) server for GitHub. It exposes GitHub operations as MCP tools over HTTP, so any MCP-compatible client can interact with GitHub repositories without needing a built-in GitHub connector.

The GitHub PAT lives server-side only. Clients authenticate to the bridge using a shared CONNECTOR_SECRET.

How it works

MCP Client  ──bearer token──▶  github-mcp-bridge  ──GitHub PAT──▶  GitHub API

1. The client sends a JSON-RPC 2.0 request to the bridge with a bearer token.

2. The bridge validates the token against CONNECTOR_SECRET (timing-safe, with rate limiting).

3. The bridge selects the correct PAT for the request owner (with fallback to the default) and calls the GitHub API.

4. The bridge maintains a server-owned MCP session for the authenticated caller so normal tool requests can resume without an explicit client-managed reinitialisation flow.

The bridge exposes tools/list so any client can discover all available tools and their input schemas at runtime — no manual tool configuration needed.

Related MCP server: GitHub Prod MCP

Session behaviour

The bridge uses server-owned sessions that are bound to the authenticated caller rather than relying on the client to preserve and replay Mcp-Session-Id on every request.

What this means

• A normal authenticated tools/list or tools/call request can succeed without an explicit prior initialize call.

• If the caller already has an active session, the bridge reuses it automatically.

• If there is no active session, the bridge creates one automatically and continues the request.

• initialize, notifications/initialized, and ping are still supported for compatibility with MCP clients that expect them.

• The bridge still returns Mcp-Session-Id headers, but the session ID is treated primarily as an internal transport/session handle rather than something every client must actively manage.

Session lifetime

The default session policy is:

• Idle timeout: 2 hours since the last valid request

• Maximum lifetime: 12 hours from session creation

• Refresh-on-use: each valid request extends the idle timeout window

These defaults can be adjusted with environment variables.

Current limitation

Sessions are currently stored in memory. That means active sessions survive normal requests in the same process, but they do not survive:

• process restarts,

• cold starts, or

• multi-instance/serverless routing without shared storage.

For durable cross-instance session continuity, replace the in-memory session store with Redis, Vercel KV, or another shared backend.

⚠️ Required parameters for MCP clients

All repo-scoped tools require owner and repo parameters. The only exception is list_repositories, which lists repositories accessible to the configured PAT and does not need repo coordinates.

Example tool call

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

Common mistake

❌ Wrong - Missing required parameters:

{
  "name": "list_branches",
  "arguments": {}
}

✅ Correct - Include owner and repo:

{
  "name": "list_branches",
  "arguments": {
    "owner": "SamNewhouse",
    "repo": "github-mcp-bridge"
  }
}

Strict validation

The server performs strict validation and will reject repo-scoped tool calls that don't include both owner and repo. This is intentional to:

1. Prevent accidental operations on wrong repositories.

2. Enable multi-PAT support — the owner selects the correct GITHUB_PAT_<OWNER> environment variable.

3. Match GitHub API requirements — all GitHub endpoints require both parameters.

If you see errors like:

Missing required parameters: 'owner' and 'repo'

You need to add these parameters to your tool calls. There are no defaults or fallbacks for repo-scoped tools.

Exception

list_repositories does not require owner and repo — it lists all repositories accessible to the configured PAT.

Available tools

Repositories

Branches

Files

Pull requests

Issues

Commits

Actions

Search

Testing

The integration tests are split into smaller files to make maintenance safer and avoid giant-file update issues.

Integration files

• tests/integration/helpers.ts

• tests/integration/repositories-branches.integration.ts

• tests/integration/pull-requests.integration.ts

• tests/integration/issues.integration.ts

• tests/integration/commits-files.integration.ts

• tests/integration/search-misc.integration.ts

• tests/integration/truncation.integration.ts

Truncation coverage

• get_file_contents truncation is tested with a real file fixture.

• get_multiple_files pagination is tested with hasMore and nextCursor.

Getting started

Prerequisites

• Node.js >= 24

• A GitHub Personal Access Token with repo scope (or a fine-grained PAT scoped to the repositories you need)

Local development

# 1. Clone the repo
git clone https://github.com/SamNewhouse/github-mcp-bridge.git
cd github-mcp-bridge

# 2. Install dependencies
npm install

# 3. Set up environment variables
cp .env.example .env
# Edit .env and fill in GITHUB_PAT and CONNECTOR_SECRET

# 4. Start the dev server (hot-reloads on change)
npm run dev

The server starts on http://localhost:3000 by default (configurable via PORT in .env).

Environment variables

Deploying

The bridge is a standard Node.js HTTP server. It can be deployed anywhere that runs Node.js.

Set the environment variables (GITHUB_PAT, CONNECTOR_SECRET, and optionally PORT, MCP_SESSION_IDLE_TTL_MS, and MCP_SESSION_MAX_TTL_MS) in your hosting environment, then run:

npm run build
npm start

Once deployed, use the root URL as the MCP endpoint and point your client at it.

Verifying the server

Health check

curl -H "Authorization: Bearer $CONNECTOR_SECRET" http://localhost:3000/health
# {"ok":true}

Discover all tools

A direct authenticated tools/list request works even when the client does not explicitly run initialize first.

curl -s -X POST http://localhost:3000 \
  -H "Authorization: Bearer $CONNECTOR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Call a tool

curl -s -X POST http://localhost:3000 \
  -H "Authorization: Bearer $CONNECTOR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_branches",
      "arguments": {
        "owner": "your-org",
        "repo": "your-repo"
      }
    }
  }'

Optional MCP initialise flow

Clients that prefer the traditional MCP initialise handshake can still use it.

curl -i -s -X POST http://localhost:3000 \
  -H "Authorization: Bearer $CONNECTOR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"initialize",
    "params":{
      "protocolVersion":"2025-03-26",
      "capabilities":{},
      "clientInfo":{"name":"example-client","version":"1.0.0"}
    }
  }'

Connecting an MCP client

Configure your MCP client with:

The client can call tools/list at any time to discover all available tools and their input schemas dynamically.

Clients that do preserve and replay Mcp-Session-Id will continue to work, but clients that do not preserve it can still use the bridge normally because the server owns session continuity.

Security

Authentication

Every request (including /health and HEAD /) requires a valid CONNECTOR_SECRET provided as:

• Authorization: Bearer <secret> header, or

• X-Api-Key: <secret> header

Secret comparison uses crypto.timingSafeEqual to prevent timing side-channel attacks.

Secret rotation

CONNECTOR_SECRET supports zero-downtime rotation via a comma-separated list:

CONNECTOR_SECRET="newSecret,oldSecret"

A request is authorised if it matches any entry. Once all clients have rotated to the new secret, remove the old one.

Rate limiting

Failed authentication attempts are tracked per IP in-memory. After 10 failures within a 15-minute window, the IP is blocked for 15 minutes. The counter resets on successful authentication.

Note: The rate limiter is per-process. On serverless runtimes such as Vercel, each cold start gets a fresh counter. For persistent cross-instance enforcement, swap the in-memory store for a shared backend such as Redis.

Session safety

Server-owned sessions are bound to the authenticated caller identity, and authentication is still checked on every request. A live session is a continuity mechanism, not an authentication substitute.

Security headers

The public splash page (GET /) is served with:

• Content-Security-Policy

• X-Content-Type-Options: nosniff

• X-Frame-Options: DENY

• Referrer-Policy: no-referrer

Best practices

• Keep GITHUB_PAT server-side only — never expose it to clients

• Use a fine-grained PAT with the minimum repository permissions needed

• Use a minimum 32-character random CONNECTOR_SECRET — generate with openssl rand -hex 32

• Rotate CONNECTOR_SECRET immediately if it is ever exposed

• Rotate GITHUB_PAT immediately if it is ever exposed

• Never log or commit secrets

Scripts