github-mcp-server

Your own remote MCP server that talks to GitHub. Runs on Vercel's serverless functions — no device stays on, no self-hosting. Ship it once, then point any MCP client at the URL.

What's in the box

Auth: send your GitHub PAT as Authorization: Bearer <token> on each request, or set a GITHUB_TOKEN env var on Vercel if this deployment is only for you. The server stores nothing.

The tools

push_file creates a real commit. For a new file it just writes; for an existing file it reads the current blob sha first, then updates it. Files over 1 MB are rejected up front — that's GitHub's own limit for the contents API.

get_file_contents returns a directory listing when the path is a folder, and truncates files past 200 000 characters so one big file can't eat a context window.

Related MCP server: github-mcp-tool

1. Get a GitHub token

GitHub → Settings → Developer settings → Personal access tokens → generate one. Fine-grained, scoped to the repos it should touch:

• Contents: read/write — only if you want push_file

• Issues: read/write — only if you want create_issue

• Read-only tokens still get all four read tools

2. Deploy to Vercel

git clone https://github.com/Ankush-das444/GitHub-mcp.git
cd GitHub-mcp
npm install

npm install -g vercel   # if you don't have it
vercel login
vercel --prod

Vercel gives you a URL like https://github-mcp-server-yourname.vercel.app. Your MCP endpoint is https://github-mcp-server-yourname.vercel.app/api/mcp, and the dashboard is at the root of that same deployment.

To bake the token in server-side instead of sending it per request:

vercel env add GITHUB_TOKEN

3. Test it locally

No Vercel account required — dev.mjs serves public/ and routes /api/mcp to the exact handler Vercel runs:

npm run serve          # http://localhost:3000

Or use Vercel's own runner:

npm run dev            # vercel dev

Then in another terminal:

# health check — plain JSON, no token needed
curl http://localhost:3000/api/mcp

# the real thing — MCP over POST
curl -X POST http://localhost:3000/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_GITHUB_PAT" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Both headers matter: the Streamable HTTP transport returns 406 if Accept doesn't list both application/json and text/event-stream. Replies come back as an SSE stream (data: {…}), so pipe through grep '^data: ' if you want just the JSON.

4. Run the tests

npm test

They boot api/mcp.js and dev.mjs behind real HTTP servers and speak MCP to them: the handshake, tools/list, CORS preflight, path traversal, every error path, and the dashboard's own script in a DOM. The one test that reaches api.github.com skips itself when there's no network.

5. Connect it anywhere — the URL is the whole setup

A remote MCP server is just a URL. You do not need a settings file.

• claude.ai: Settings → Connectors → Add custom connector → paste https://YOUR-DEPLOY.vercel.app/api/mcp.

• Claude Desktop / Cursor: the same "add a server by URL" dialog.

That's it. The only extra field is an optional header — Authorization: Bearer <PAT> — and only if this deployment doesn't carry its own GITHUB_TOKEN. Set the token on Vercel and the bare URL is the entire configuration.

If some older client genuinely only reads a file, the same URL goes in as:

Claude Code

claude mcp add --transport http github https://YOUR-DEPLOY.vercel.app/api/mcp \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://YOUR-DEPLOY.vercel.app/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_GITHUB_PAT" }
    }
  }
}

The dashboard

public/index.html is a single file, no build step, no external requests. Open it at the root of your deployment (or npm run serve locally) and it:

• performs a real MCP initialize + tools/list against the endpoint and shows the server name, version, tool count and handshake latency — the flow diagram only animates when the handshake actually succeeds

• builds each tool's argument form from the inputSchema the server reports, so adding a tool server-side adds it to the UI with no frontend change

• runs tool calls for real and shows the exact JSON-RPC request, the response, and the equivalent curl

• refuses to run create_issue or push_file until you tick a box acknowledging that it writes to GitHub

• keeps your token in sessionStorage for the tab only — never localStorage, never sent anywhere but the endpoint you typed

If the endpoint is unreachable it falls back to the documented tool list and says so, rather than silently showing a stale "online".

How it behaves under failure

Every failure a tool hits comes back as a normal MCP tool result with isError: true and a human-readable message — never a bare JSON-RPC -32603. A model can only act on what's inside a tool result, and a GitHub 404 is a data problem, not a protocol problem. So you get:

401 from GitHub — the token was rejected. Bad credentials
403 from GitHub — the token lacks a required scope, or the rate limit is exhausted. …
404 from GitHub — wrong owner/repo/path, the branch does not exist, or the token cannot see this resource. …
Invalid arguments for get_repo. owner: Required

Argument validation runs before auth, so a malformed call is told about the payload instead of being sent off to discover its token is missing. Obviously wrong tokens (Bearer Bearer, a pasted URL, two tokens in one header) are rejected before any request leaves the function.

Notes

• SDK version. @modelcontextprotocol/sdk moves between releases. This is tested against 1.30.0, resolved from the ^1.12.0 range. If a future major breaks the Streamable HTTP signature, pin the version and check the changelog.

• Stateless by design (sessionIdGenerator: undefined). Each request builds a fresh Server + transport, so there's no session to persist — which is the only thing that works on serverless. Each tool call is self-contained.

• GET is a health check. It returns the server identity and tool list as JSON. MCP itself is POST-only; PUT/DELETE get a 405 with an Allow header.

• CORS is open (Access-Control-Allow-Origin: *) and OPTIONS preflights are answered, because browser-based clients need it. That is safe because auth is per-request: the server holds no credentials of its own. If you bake GITHUB_TOKEN into the deployment, tighten CORS_HEADERS in api/mcp.js to your own origin.

• Never commit your PAT. Use a Vercel env var, or pass it per request from the client config.

Adding more tools

Add an entry to the TOOLS array in api/mcp.js — name, description, inputSchema (JSON schema for the client), schema (zod, for runtime validation), and handler(octokit, args). If it mutates anything, add its name to WRITE_TOOLS so the dashboard gates it. Octokit's REST methods cover almost everything: https://octokit.github.io/rest.js