GitHub Intelligence MCP Server

An enterprise-oriented Model Context Protocol (MCP) server that connects AI assistants to GitHub: repositories, issues, commits, related files, and (optionally) pull request actions.

Overview

Problem: AI agents need structured, authenticated access to GitHub data without ad-hoc scraping or fragile prompts.

Solution: This server exposes a small, typed tool surface over the GitHub REST API. MCP clients (Cursor, Claude Desktop, custom agents) call tools by name; the server validates input, applies policy for write operations, and returns normalized JSON.

Who it is for: Teams building AI-assisted triage, code exploration from issues, or semi-automated PR workflows where read access is always on and writes are explicit and gated.

Architecture

┌─────────────────┐     stdio (MCP)      ┌──────────────────────────┐
│  MCP client     │ ◄──────────────────► │  github-intelligence-mcp │
│  (Cursor, etc.) │                      │  (TypeScript + MCP SDK)   │
└─────────────────┘                      └────────────┬─────────────┘
                                                      │
                                                      │ HTTPS
                                                      ▼
                                           ┌─────────────────────┐
                                           │  GitHub REST API     │
                                           └─────────────────────┘

• Transport: stdio (typical for local MCP servers).
• Read tools: Allowed for all configured clients by default.
• Write tools: Disabled unless you explicitly enable them and assign a sufficient role (see Environment variables).

Tool reference

Registered tool names match what MCP clients must invoke (snake_case with github_ prefix).

Read tools

Tool	Purpose
github_get_repository	Repository metadata (description, stars, open issues, default branch).
github_list_open_issues	Open issues; optional limit caps how many are returned.
github_get_issue_by_number	Full issue payload for a given issue number.
github_find_related_files_for_issue	Keyword-style search over the repo to suggest files related to an issue.
github_get_recent_commits	Recent commits on the default branch.

Write tools (optional)

Tool	Purpose
github_create_pull_request	Open a PR from head into base (e.g. feature branch → main).
github_add_pull_request_review	Submit COMMENT, APPROVE, or REQUEST_CHANGES on a PR.

Write tools require ENABLE_WRITE_TOOLS=true and a role of repo_writer or admin via MCP_USER_ROLE. See policy in src/utils/policy.ts.

Prerequisites

• Node.js 18 or newer
• npm (or compatible package manager)
• GitHub Personal Access Token (PAT) with scopes appropriate to your use case:
  • Read-only workflows: public_repo (public repos) or repo (private repos).
  • Creating PRs or reviews: typically repo and pull request permissions as required by your org.

Installation

git clone https://github.com/meltemeroglu/github-intelligence-mcp.git
cd github-intelligence-mcp
npm install
npm run build

Run the compiled server:

npm start

Development (no separate build step):

npm run dev

Inspect tools interactively:

npm run inspect

Environment variables

Variable	Purpose
GITHUB_TOKEN	Authenticates GitHub API calls. Strongly recommended to avoid low unauthenticated rate limits and to access private repositories.
ENABLE_WRITE_TOOLS	Set to true to allow write tools. Default behavior keeps writes off.
MCP_USER_ROLE	read_only (default), repo_writer, or admin. Write tools require repo_writer or admin when enabled.
REQUIRE_WRITE_APPROVAL	Exposed in policy responses for clients; default true (see .env.example).
WRITE_TOOLS_DRY_RUN	Default true: write tools return a dry-run plan without calling mutating GitHub APIs. Set to false for live PR/review operations.

Copy .env.example to .env and adjust values, or export variables in your shell. Example for read-only local use:

export GITHUB_TOKEN="ghp_xxxxxxxx"
npm start

Security notes: Do not commit tokens. Prefer environment variables or your MCP host’s secret store. Use a PAT with minimal scopes. Treat write tools as production controls: enable only where needed and use dry-run until you trust your automation.

Live writes: With WRITE_TOOLS_DRY_RUN=false, mutating tools still expect approved: true on the tool call before performing the GitHub API action (see src/tools/write/createPullRequest.ts and src/tools/write/addPullRequestReview.ts).

MCP client configuration (Cursor example)

Add a server entry that runs this package via Node. Adjust paths to your clone.

{
  "mcpServers": {
    "github-intelligence": {
      "command": "node",
      "args": ["/absolute/path/to/github-intelligence-mcp/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
      }
    }
  }
}

For development you can point args at tsx and the src/index.ts entry if your setup supports it, or run npm run build and use dist/index.js as above.

Usage examples (prompts)

These work well with agents that already have this MCP server enabled.

Repository snapshot

Using github_get_repository, summarize owner/repo: default branch, stars, and open issue count.

Triage

Call github_list_open_issues for owner/repo with a limit of 10. Group issues by likely theme.

Deep dive on one issue

Fetch issue #N with github_get_issue_by_number, then use github_find_related_files_for_issue and outline what to change.

Recent changes

Use github_get_recent_commits and summarize the last five commits in one paragraph.

Pull request (writes enabled)

After I push branch fix/readme-typo, create a PR into main with github_create_pull_request with a clear title and body.

Example workflow: issue → plan → PR

1. github_list_open_issues — pick an issue.
2. github_get_issue_by_number — read scope and acceptance criteria.
3. github_find_related_files_for_issue — locate candidate files.
4. Implement changes locally; commit and push a branch.
5. With write tools enabled and dry-run off: github_create_pull_request from your branch to the target base.
6. Optional: github_add_pull_request_review for automated or human-in-the-loop review events.

Troubleshooting

Symptom	Check
403 or rate limit errors	Set GITHUB_TOKEN; confirm token is valid and not expired.
Write tool “disabled” or unauthorized	ENABLE_WRITE_TOOLS=true, MCP_USER_ROLE=repo_writer or admin, and WRITE_TOOLS_DRY_RUN=false if you need real API writes.
Empty or partial issue lists	GitHub pagination and filters; confirm owner/repo strings and that issues are not pull requests (server filters PRs where applicable).

Contributing

1. Fork the repository and create a branch (feature/… or fix/…).
2. Keep changes focused; match existing TypeScript style.
3. Run npm run build before submitting.
4. Open a pull request with a clear description.

For larger features, open an issue first to align on scope.

Scripts

Script	Command
Develop	npm run dev
Build	npm run build
Production	npm start
MCP Inspector	npm run inspect

License

MIT (see package.json).