How to Build an MCP Server for GitHub

mkdir github-mcp && cd github-mcp
npm init -y && npm pkg set type=module
npm install @modelcontextprotocol/[email protected] [email protected]
npm install -D @modelcontextprotocol/[email protected] tsx@4

// server.ts - a read-only GitHub MCP server on the v2 TypeScript SDK.
// Works unauthenticated for public repos; set GITHUB_TOKEN for higher
// rate limits and private repos.
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";

const API = "https://api.github.com";
const TOKEN = process.env.GITHUB_TOKEN;

async function gh(path: string): Promise<any> {
  const headers: Record<string, string> = {
    Accept: "application/vnd.github+json",
    "User-Agent": "github-mcp-server",
    "X-GitHub-Api-Version": "2022-11-28",
  };
  if (TOKEN) headers.Authorization = `Bearer ${TOKEN}`;
  const res = await fetch(`${API}${path}`, { headers });
  if (!res.ok) {
    const body = await res.text();
    throw new Error(`GitHub API ${res.status} on ${path}: ${body.slice(0, 200)}`);
  }
  return res.json();
}

function makeServer() {
  const server = new McpServer(
    { name: "github", version: "1.0.0" },
    { capabilities: { tools: {} } },
  );

  server.registerTool(
    "get_repo",
    {
      title: "Get repository",
      description: "Fetch metadata for a public GitHub repository.",
      inputSchema: z.object({ owner: z.string(), repo: z.string() }),
    },
    async ({ owner, repo }) => {
      const r = await gh(`/repos/${owner}/${repo}`);
      const out = {
        full_name: r.full_name,
        description: r.description,
        stars: r.stargazers_count,
        language: r.language,
        open_issues: r.open_issues_count,
        url: r.html_url,
      };
      return { content: [{ type: "text", text: JSON.stringify(out, null, 2) }] };
    },
  );

  server.registerTool(
    "list_issues",
    {
      title: "List issues",
      description: "List open issues for a repository, most recent first.",
      inputSchema: z.object({
        owner: z.string(),
        repo: z.string(),
        limit: z.number().int().min(1).max(30).default(5),
      }),
    },
    async ({ owner, repo, limit }) => {
      const issues = await gh(
        `/repos/${owner}/${repo}/issues?state=open&per_page=${limit}`,
      );
      const rows = issues
        .filter((i: any) => !i.pull_request) // the issues endpoint also returns PRs
        .map((i: any) => `#${i.number} ${i.title} (${i.comments} comments)`);
      return { content: [{ type: "text", text: rows.join("\n") || "No open issues." }] };
    },
  );

  server.registerTool(
    "get_file",
    {
      title: "Get file contents",
      description: "Read a UTF-8 text file at an optional ref (branch, tag, or SHA).",
      inputSchema: z.object({
        owner: z.string(),
        repo: z.string(),
        path: z.string(),
        ref: z.string().optional(),
      }),
    },
    async ({ owner, repo, path, ref }) => {
      const q = ref ? `?ref=${encodeURIComponent(ref)}` : "";
      const r = await gh(`/repos/${owner}/${repo}/contents/${path}${q}`);
      if (Array.isArray(r)) throw new Error(`${path} is a directory, not a file`);
      const text = Buffer.from(r.content, "base64").toString("utf8");
      return { content: [{ type: "text", text: text.slice(0, 4000) }] };
    },
  );

  return server;
}

serveStdio(() => makeServer());

// test-client.ts - spawn the server, call each tool against a real repo, assert.
import { Client } from "@modelcontextprotocol/client";
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["tsx", new URL("./server.ts", import.meta.url).pathname],
});
const client = new Client({ name: "test", version: "1.0.0" });
await client.connect(transport);

function assert(cond: unknown, msg: string) {
  if (!cond) throw new Error("ASSERT FAILED: " + msg);
  console.log("  ok - " + msg);
}

const { tools } = await client.listTools();
assert(tools.length === 3, "3 tools registered");

const repo = await client.callTool({
  name: "get_repo",
  arguments: { owner: "modelcontextprotocol", repo: "modelcontextprotocol" },
});
const info = JSON.parse((repo.content as any)[0].text);
assert(info.full_name === "modelcontextprotocol/modelcontextprotocol", "get_repo returns full_name");
assert(typeof info.stars === "number" && info.stars > 0, "get_repo returns star count");

// The error path: a missing repo must come back as a tool error, not a crash.
const bad = await client.callTool({
  name: "get_repo",
  arguments: { owner: "modelcontextprotocol", repo: "does-not-exist-xyz" },
});
assert(bad.isError === true, "missing repo returns a tool error");

await client.close();
console.log("\nALL CHECKS PASSED");

npx tsx test-client.ts
# ...
# ALL CHECKS PASSED

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/github-mcp/server.ts"],
      "env": { "GITHUB_TOKEN": "ghp_your_token_here" }
    }
  }
}