GitHub GraphQL MCP Server for Repositories, Issues, PRs

Overview

This MCP (Model Context Protocol) server provides a simple HTTP bridge between LLMs (or any MCP-aware client) and GitHub’s GraphQL API. Instead of embedding raw GraphQL queries in your application, the server exposes focused, reusable “tools” that return curated repository, issue, and pull request context suitable for model prompts. That reduces token usage, centralizes access control, and makes it easier to fetch the exact fields models need.

It’s useful when you want to enrich prompts with up-to-date GitHub data (file trees, README, issue timelines, PR diffs/comments) without leaking your GraphQL token into many clients. The server handles authentication, pagination, light caching, and shaping of GraphQL responses into smaller, predictable payloads for model consumption.

Features

• Focused MCP tools for GitHub repositories, issues, and pull requests
• Uses GitHub GraphQL API for flexible, efficient queries
• Centralized authentication via a single GitHub token
• Shaped responses optimized for LLM context (summaries, timelines, diffs)
• Optional caching and pagination handling
• Docker and local startup options for development and deployment

Installation / Configuration

Clone and install (Node.js/npm example):

git clone https://github.com/QuentinCody/github-graphql-mcp-server.git
cd github-graphql-mcp-server
npm install

Set required environment variables (example .env):

# .env
GITHUB_TOKEN=ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXX
PORT=3000
CACHE_TTL=300  # seconds, optional
LOG_LEVEL=info

Start the server:

# development
npm run dev

# production
npm start

Docker (build and run):

docker build -t github-mcp-server .
docker run -e GITHUB_TOKEN="$GITHUB_TOKEN" -p 3000:3000 github-mcp-server

Configuration table

Available Tools / Resources

The server exposes a small set of MCP-style endpoints/tools tailored to common GitHub needs. Endpoints below are illustrative — actual paths may vary but follow the same idea.

• GET /health — basic health check
• POST /tools/repository — fetch repository context (metadata, topics, README, file list)
• POST /tools/issue — fetch issue details, timeline, comments
• POST /tools/pull_request — fetch PR description, diffs/statistics, review comments

Example: Request repository context

curl -X POST "http://localhost:3000/tools/repository" \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "octocat",
    "repo": "Hello-World",
    "paths": ["README.md", "src/**"],
    "max_files": 10
  }'

Example: Request issue context

curl -X POST "http://localhost:3000/tools/issue" \
  -H "Content-Type: application/json" \
  -d '{"owner":"octocat","repo":"Hello-World","number":42,"include_timeline":true}'

Responses are JSON objects containing curated fields (title, body, author, timeline events, diffs snippets) designed for inclusion in prompts.

Use Cases

1. Summarize a PR conversation for code-review assistants

   • Flow: MCP client asks the server for PR #123 context → server returns PR description, changed files summary, latest review comments and statuses → LLM generates a concise review summary or checklist.
   • Benefit: Models get focused conversation history plus diffs without needing full repo clones.

2. Auto-triage or suggest labels for new issues

   • Flow: On issue creation, fetch issue body, labels, and recent similar issues → pass to model to recommend severity/labels or a template response.
   • Benefit: Reduces manual triage by giving models the right context (past issues + metadata).

3. Build a code-aware chat assistant

   • Flow: Chat session needs the latest README and code snippets for context → client requests repository tool for README and matching source files → model responds with code examples, usage instructions, or debugging tips.
   • Benefit: Keeps assistant replies current with repository state via GraphQL queries shaped for consumption.

Examples: GraphQL snippets (for reference)

Repository metadata query (simplified):

query RepoMeta($owner: String!, $name: String!) {
  repository(owner: $owner, name: $name) {
    name
    description
    primaryLanguage { name }
    repositoryTopics(first:10) { nodes { topic { name } } }
    defaultBranchRef { name }
    readme: object(expression: "HEAD:README.md") { ... on Blob { text } }
  }
}

Issue timeline query (simplified):

query IssueTimeline($owner: String!, $name: String!, $number: Int!) {
  repository(owner:$owner, name:$name) {
    issue(number:$number) {
      title
      bodyText
      author { login }
      comments(last:50) { nodes { author { login } bodyText createdAt } }
      timelineItems(last:50) { nodes { __typename ... on LabeledEvent { label { name } } } }
    }
  }
}

These queries are representative of what the server executes under the hood to assemble compact, model-friendly responses.

Notes and Next Steps

• Ensure your GITHUB_TOKEN has the minimal scopes needed (typically repo/public_repo depending on target repositories).
• Consider placing the MCP server behind an internal network or gateway to control access to your token.
• For production, enable caching, rate-limit requests, and monitor GraphQL error responses to avoid hitting GitHub rate limits.

For the latest usage details and any additional endpoints, refer to the repository at: https://github