TypeScript MCP Server with GitHub Integration

Overview

This template provides a fully production-ready Model Context Protocol (MCP) server built with TypeScript, using HTTP transport and API key authentication. It integrates directly with the GitHub REST API to expose powerful repository management capabilities as MCP tools that Claude and other AI assistants can invoke.

The server is designed for engineering teams who want to give their AI assistants real access to GitHub workflows — searching repositories, managing issues, reviewing pull requests, and inspecting commit history — all through a secure, observable, and deployable service. It follows the MCP specification precisely while layering in production concerns like structured logging, health monitoring, and container-based deployment.

Whether you are building an internal developer assistant, automating triage workflows, or exploring AI-native DevOps tooling, this template gives you a solid, extensible foundation. Every component — authentication middleware, structured logging with Pino, health checks, and Docker configuration — is wired together and ready to deploy.

What You'll Learn

How to implement an MCP server using the @modelcontextprotocol/sdk with HTTP/SSE transport
How to register and validate MCP tools using Zod schemas with full TypeScript inference
How to implement API key authentication as Express middleware protecting all MCP endpoints
How to integrate with the GitHub REST API using Octokit with proper pagination and error handling
How to set up Pino for structured JSON logging with request correlation IDs and configurable log levels
How to build a /health endpoint that checks each external dependency and returns structured JSON status
How to write a multi-stage Dockerfile that produces a minimal, secure production image
How to configure docker-compose for local development with live environment variable injection
How to handle and surface GitHub API errors (rate limits, permissions, not-found) as structured MCP errors
How to load and validate all configuration from environment variables with typed defaults
How to structure a TypeScript MCP project for maintainability and extensibility
How to test MCP tools locally using curl and via Claude Desktop configuration

Architecture

Claude Desktop / MCP Client
        │
        │  HTTP POST /mcp  (Bearer API Key)
        ▼
   Express Server
        │
        ├── API Key Auth Middleware  (src/auth.ts)
        │         │
        │    [401 if invalid]
        │
        ├── Correlation ID Middleware  (src/logger.ts)
        │
        ├── MCP HTTP Transport  (src/server.ts)
        │         │
        │    MCP Protocol Layer (@modelcontextprotocol/sdk)
        │         │
        │    Tool Router
        │    ├── github_search_repos
        │    ├── github_list_issues
        │    ├── github_get_pull_request
        │    └── github_list_commits
        │         │
        │    Octokit GitHub Client
        │         │
        │         ▼
        │    GitHub REST API (api.github.com)
        │
        └── GET /health  (src/health.ts)
                  │
             Checks: GitHub API reachability
             Returns: { status, version, checks, uptime }

Project Structure

github-mcp-server/
├── src/
│   ├── server.ts          # Main MCP server, tool registration, Express app
│   ├── config.ts          # Environment variable loading and validation
│   ├── auth.ts            # API key authentication middleware
│   ├── logger.ts          # Pino structured logger with correlation IDs
│   └── health.ts          # /health endpoint with dependency checks
├── Dockerfile             # Multi-stage production Docker build
├── docker-compose.yml     # Local development with env file support
├── package.json           # Dependencies with pinned versions
├── tsconfig.json          # TypeScript compiler configuration
├── .env.example           # All environment variables documented
└── .gitignore             # TypeScript/Node.js gitignore

Prerequisites

Node.js 20 or later
npm 9 or later
A GitHub Personal Access Token (classic or fine-grained) with repo and read:org scopes
Docker and Docker Compose (for containerised development/deployment)
A Claude Desktop installation (for end-to-end testing)

Quick Start

# 1. Clone or download the template
git clone https://github.com/your-org/github-mcp-server.git
cd github-mcp-server

# 2. Install dependencies
npm install

# 3. Configure environment
cp .env.example .env
# Edit .env — set GITHUB_TOKEN and MCP_API_KEY at minimum

# 4. Build TypeScript
npm run build

# 5. Start the server
npm start
# Server is now running on http://localhost:3000

# 6. Verify health
curl http://localhost:3000/health

# 7. Test a tool call (replace YOUR_API_KEY)
curl -X POST http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# --- OR run with Docker Compose ---
docker compose up --build

Features

4 GitHub MCP tools: search repositories, list issues, inspect pull requests, view commit history
API key authentication: every MCP request validated via Bearer token middleware
Pino structured logging: JSON output, configurable log level, per-request correlation IDs
Health endpoint: /health checks GitHub API reachability and returns structured JSON
Multi-stage Docker build: build stage compiles TypeScript, production stage runs minimal Node.js Alpine image
Docker Compose: one-command local development with .env file injection
Zod input validation: all tool inputs validated with descriptive error messages before calling GitHub
GitHub error handling: rate limits, 404s, permission errors surfaced as structured MCP errors
Graceful shutdown: SIGTERM/SIGINT handlers close connections cleanly
Typed configuration: all environment variables loaded and typed via src/config.ts

Works With

Claude Desktop — add the server to claude_desktop_config.json using the url transport
Claude Code — use as a remote MCP server with --mcp-server flag
Cursor — configure in Cursor MCP settings with the HTTP endpoint
Windsurf — add as an HTTP MCP server in Windsurf plugin configuration
Continue — register as an MCP server in config.json under mcpServers

Configuration

Variable	Description	Required
`PORT`	HTTP port the server listens on	Optional (default: `3000`)
`HOST`	Host/interface to bind to	Optional (default: `0.0.0.0`)
`MCP_API_KEY`	Secret API key clients must send as Bearer token	Required
`GITHUB_TOKEN`	GitHub Personal Access Token (classic or fine-grained)	Required
`GITHUB_DEFAULT_ORG`	Default GitHub org used when org is not provided in tool call	Optional
`LOG_LEVEL`	Pino log level: `trace`, `debug`, `info`, `warn`, `error`	Optional (default: `info`)
`NODE_ENV`	Runtime environment: `development` or `production`	Optional (default: `production`)
`GITHUB_API_TIMEOUT_MS`	Timeout in ms for GitHub API requests	Optional (default: `10000`)

Deployment

Docker (standalone)

# Build the production image
docker build -t github-mcp-server:latest .

# Run with environment variables
docker run -d \
  --name github-mcp-server \
  -p 3000:3000 \
  -e MCP_API_KEY=your_secret_key \
  -e GITHUB_TOKEN=ghp_your_token \
  -e LOG_LEVEL=info \
  github-mcp-server:latest

# Check logs
docker logs -f github-mcp-server

Docker Compose (local development)

# Start with hot-reload friendly config
docker compose up --build

# Stop
docker compose down

Railway

# Install Railway CLI
npm install -g @railway/cli

# Login and initialise
railway login
railway init

# Set environment variables
railway variables set MCP_API_KEY=your_secret_key
railway variables set GITHUB_TOKEN=ghp_your_token
railway variables set LOG_LEVEL=info

# Deploy
railway up

Fly.io

# Install flyctl and login
curl -L https://fly.io/install.sh | sh
fly auth login

# Launch app (follow prompts, choose the Dockerfile option)
fly launch --name github-mcp-server

# Set secrets
fly secrets set MCP_API_KEY=your_secret_key
fly secrets set GITHUB_TOKEN=ghp_your_token

# Deploy
fly deploy

# Check status
fly status
fly logs

Production Checklist

MCP_API_KEY is a cryptographically random string (minimum 32 characters)
GITHUB_TOKEN uses a fine-grained PAT scoped to only the required repositories
NODE_ENV is set to production in all deployment environments
LOG_LEVEL is set to info or warn in production (not debug or trace)
Health endpoint /health is monitored by an uptime service (e.g. UptimeRobot, Better Uptime)
Docker image is built from the multi-stage Dockerfile (not the dev stage)
Container runs as a non-root user (configured in Dockerfile)
API key is stored in a secrets manager (Railway secrets, Fly secrets, AWS Secrets Manager)
GitHub token is rotated on a schedule and has minimal required scopes
HTTPS/TLS is terminated at the load balancer or reverse proxy in front of this service
Rate limiting is configured at the ingress level to protect against abuse
Structured logs are being shipped to a log aggregation platform (Datadog, Loki, CloudWatch)
/health endpoint is NOT protected by API key auth (so monitoring tools can access it)
Graceful shutdown is tested — server drains in-flight requests before exiting
Docker image is scanned for vulnerabilities before deployment (e.g. docker scout, Trivy)

Testing

Manual testing with curl

# List all available tools
curl -s -X POST http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | jq

# Search GitHub repositories
curl -s -X POST http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "github_search_repos",
      "arguments": { "query": "mcp server language:typescript", "per_page": 5 }
    }
  }' | jq

# List open issues for a repository
curl -s -X POST http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "github_list_issues",
      "arguments": { "owner": "microsoft", "repo": "vscode", "state": "open", "per_page": 10 }
    }
  }' | jq

# Verify authentication is enforced (should return 401)
curl -s -o /dev/null -w "%{http_code}" -X POST http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Testing with Claude Desktop

Add the following to your claude_desktop_config.json (found at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "github-mcp": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Restart Claude Desktop. You can then ask Claude: "Search GitHub for TypeScript MCP server examples" or "List the open issues in microsoft/vscode" and Claude will invoke the tools automatically.

TypeScript MCP Server with GitHub Integration

Files(10)

TypeScript MCP Server with GitHub Integration

Overview

What You'll Learn

Architecture

Project Structure

Prerequisites

Quick Start

Features

Works With

Configuration

Deployment

Docker (standalone)

Docker Compose (local development)

Railway

Fly.io

Production Checklist

Testing

Manual testing with curl

Testing with Claude Desktop