Model Context Protocol (MCP) server for GitHub Issues, Pull Requests, and Projects.

Designed by belsar.ai to enable AI assistants to manage your GitHub workflow with ease and efficiency.

This MCP server uses a Script Execution architecture. Instead of exposing dozens of restricted tools, it exposes a single, powerful tool: execute_github_script.

This allows the AI to write and execute secure JavaScript code to interact with your GitHub repository directly. This enables:

• Complex Workflows: "Find all open bugs without a milestone, assign them to 'Sprint 1', and add the 'high-priority' label" (1 turn vs. 20 turns).
• Batch Operations: Update dozens of issues in a single shot.
• Data Processing: Filter, sort, and aggregate issue data using standard JavaScript.
• Efficiency: Drastically reduces context usage and latency.

1. Generate a Token: Create a GitHub Personal Access Token (Classic) with repo and project (V2) scopes.
2. Set Environment Variable: Set GITHUB_MCP_PAT in your environment (e.g., in your .bashrc, .zshrc, or ~/.gemini/.env).
3. Pick the install command for your platform:

claude mcp add --transport stdio github -- npx -y @belsar-ai/gh-mcp

codex mcp add github -- npx -y @belsar-ai/gh-mcp

gemini extensions install https://github.com/belsar-ai/gh-mcp

4. Configure your Repo: Create a .mcp-config/gh-mcp.toml in your project root (see Configuration below).

This tool requires a gh-mcp.toml file to know which repository to manage. It searches for this file in the current directory or a .mcp-config/ subdirectory, walking up the tree until found.

[required]
repo_url = "https://github.com/owner/repo"

[optional]
# If provided, new issues are automatically added to this Project (V2) board by name
project_name = "Product Roadmap"

# Automatically assign this milestone to new issues if not specified
current_milestone = "v1.0 Release"

To uninstall:

claude mcp remove github

codex mcp remove github

gemini extensions uninstall gh-mcp

The AI can now handle complex repository management in a single shot:

List all open bugs and summarize the top 3 most recent ones.

Find all issues tagged 'stale' and close them with a comment "Closing due to inactivity".

Create a new feature request for "Dark Mode" and add it to my 'Product Roadmap' project.

Show me PR #245 and tell me if any checks failed.

Get the logs from the failed workflow run.

The AI has access to a global github object with the following methods:

• listIssues(limit?, openOnly?, milestone?): List issues, optionally filter by milestone.
• getIssue(number): Get full details for a specific issue.
• searchIssues(query): Search using GitHub syntax (auto-scoped to your repo).
• createIssue({ title, body?, labels?, milestone?, issueType?, parentIssueId? }): Create a new issue.
• updateIssue(number, { title?, body?, state? }): Update an issue.
• deleteIssue(number): Delete an issue.

• getPullRequest(number): Get PR with description, comments, review threads, and CI check status.
• getWorkflowLogs(runId): Get logs from failed GitHub Actions jobs (run IDs shown in PR checks).

• getLabels(): List all available labels in the repo.
• addLabels(number, labels[]): Add labels to an issue.
• removeLabels(number, labels[]): Remove labels from an issue.
• getMilestones(): List open milestones.
• createMilestone({ title, description?, dueOn?, state? }): Create a new milestone.
• updateMilestone(idOrTitle, { title?, description?, dueOn?, state? }): Update a milestone.
• getIssueTypes(): List available issue types (for organizations with custom types).

• getRepoInfo(): Get owner and repo name.
• getCurrentMilestone(): Get the default milestone from your config.
• getContextIds(): Get internal IDs for labels, milestones, etc. (cached).
• help(): Show full API documentation with examples and search tips.

• Token Issues: Ensure GITHUB_MCP_PAT is correctly set and has repo scope.
• Cache: Metadata (IDs) is cached in .mcp-config/gh-mcp-cache.json. Delete this file to force a refresh if you add new labels or milestones.
• Config Not Found: Ensure .mcp-config/gh-mcp.toml exists in your project or a parent directory.