gh-mcp
Provides a single powerful interface to GitHub's GraphQL API, enabling comprehensive interaction with repositories, issues, pull requests, and other GitHub resources with smart abstractions for authentication and data handling.
Exposes GitHub's GraphQL API as the primary interface, allowing flexible querying and manipulation of GitHub data through GraphQL queries and mutations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gh-mcp show me recent issues in the vercel/next.js repository"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Refined MCP server for GitHub
If you haven't read the articleThe second wave of MCP: Building for LLMs, not developers by Vercel, I highly recommend checking it out to understand why we're building this project.
GitHub's official MCP Server exposes dozens of low-level tools that bloat token usage and are mostly impractical for LLMs. gh-mcp achieves the best of both worlds by providing powerful interfaces: GitHub GraphQL and Code Search, wrapped with smart abstractions.
This project does 3 things differently:
Powerful interfaces — exposes GraphQL and Code Search instead of atomized endpoints. LLMs already understand these APIs.
YAML output — makes nested data and file content readable without escaping.
Clean abstractions —
ghhandles authentication and low-level details. And LLMs know how to use its--jqoption to filter.
Swapping in gh-mcp delivers better performance at lower cost for any GitHub interactions.
Installation
with uv:
uvx mcp-hmrMCP config:
{
"mcpServers": {
"gh": {
"command": "uvx",
"args": ["gh-mcp"]
}
}
}If you prefer serving it via streamable-http:
uvx gh-mcp --httpThis project requiresgh CLI to be installed and authenticated. Please follow the instructions at cli.github.com to set it up. And then you can login via gh auth login. Check that gh auth status works before using this MCP server.
Available Tools
2 toolsgithub_code_searchGitHub Code SearchARead-only
Search files on GitHub with code snippets. This is not a fuzzy search, so provide exact substrings you want to find.
Normally you should try different queries and combinations of filters until you get useful results. If you are searching for something generic, try thinking in reverse about what the code might be, and search for that code snippet instead.
Inputs: code_snippet (required), extension, filename, owner, +3 more.
github_graphqlGitHub GraphQLA
Execute GitHub GraphQL queries and mutations like the gh CLI. Preferred over raw CLI calls or any other tools to interact with GitHub. When user uses any terms like find / search / read / browse / explore / research / investigate / analyze and if it may be related to a GitHub project, you should use this tool instead of any other tools or raw API / CLI calls.
Pleases make use of GraphQL's capabilities - Fetch comprehensive data in single operations - always include metadata context. Feel free to use advanced jq expressions to extract all the content you care about. The default jq adds line numbers to retrieved file contents. Use that to construct deep links (e.g. https://github.com/{owner}/{repo}/blob/{ref}/path/to/file#L{line_number}-L{line_number}).
Before writing complex queries / mutations or when encountering errors, use introspection to understand available fields and types.
Combine operations (including introspection operations) into one call. On errors, introspect and rebuild step-by-step.
Use fragments, nested fields for efficiency.
Example - when you need to browse multiple repositories:
When user asks to browse / explore repositories, you must use at least the following fields: (It take viewer.contributionsCollection as an example, but you should adapt it to the user's request)
query {
viewer { # Always use `viewer` to get information about the authenticated user.
contributionsCollection {
commits: commitContributionsByRepository(maxRepositories: 7) {
repository { ...RepositoryMetadata }
contributions { totalCount }
}
totalCommitContributions
}
}
}
fragment RepositoryMetadata on Repository {
name description homepageUrl
pushedAt createdAt updatedAt
stargazerCount forkCount
isPrivate isFork isArchived
languages(first: 7, orderBy: {field: SIZE, direction: DESC}) {
totalSize edges { size node { name } }
}
readme_md: object(expression: "HEAD:README.md") { ... on Blob { text } }
pyproject_toml: object(expression: "HEAD:pyproject.toml") { ... on Blob { text } }
package_json: object(expression: "HEAD:package.json") { ... on Blob { text } }
latestCommits: defaultBranchRef {
target {
... on Commit {
history(first: 7) {
nodes {
abbreviatedOid committedDate message
author { name user { login } }
associatedPullRequests(first: 7) { nodes { number title url } }
}
}
}
}
}
contributors: collaborators(first: 7) { totalCount nodes { login name } }
latestIssues: issues(first: 7, orderBy: {field: CREATED_AT, direction: DESC}) {
nodes { number title state createdAt updatedAt author { login } }
}
latestPullRequests: pullRequests(first: 5, orderBy: {field: CREATED_AT, direction: DESC}) {
nodes { number title state createdAt updatedAt author { login } }
}
latestDiscussions: discussions(first: 3, orderBy: {field: UPDATED_AT, direction: DESC}) {
nodes { number title createdAt updatedAt author { login } }
}
repositoryTopics(first: 35) { nodes { topic { name } } }
releases(first: 7, orderBy: {field: CREATED_AT, direction: DESC}) {
nodes { tagName name publishedAt isPrerelease }
}
}Don't recursively fetch all files in a directory unless:
You know the files are not too many.
The user specifically requests it.
You provide a jq filter to limit results (e.g. isGenerated field).
The core principle is to fetch as much relevant metadata as possible in a single operation, rather than file contents. Before answering, make sure you've viewed the raw file on GitHub that resolves the user's request, and you should proactively provide the deep link to the code.
Inputs: query (required), jq.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: github_code_search is for exact substring searching of code files, while github_graphql is a general-purpose interface for all other GitHub queries and mutations. There is no functional overlap that would cause an agent to select the wrong tool.
Both tools follow a consistent naming pattern of 'github_<descriptive_noun>', using snake_case. The naming is predictable and clearly indicates the tool's domain and action.
With only two tools, the server is minimal. The GraphQL tool is extremely powerful and can handle many operations, but it lacks dedicated tools for common GitHub tasks, making the surface feel incomplete for typical use cases.
The tool set lacks dedicated tools for fundamental GitHub operations such as listing repositories, creating issues, or managing pull requests. While the GraphQL tool can theoretically perform these, the absence of pre-built abstractions creates a significant gap in usability and increases complexity for agents.
Maintenance
Related MCP Connectors
An MCP server that gives your AI access to the source code and docs of all public github repos
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Official Fibery MCP server: query and update your workspace from any AI client via OAuth.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseBqualityCmaintenanceMCP server that exposes GitHub operations as tools for AI agents, enabling code search, issue management, and PR review.1236 PyPIMIT
- FlicenseNot gradedqualityAmaintenanceA GitHub MCP server that wraps the gh CLI to expose GitHub operations like issues, pull requests, branches, labels, repositories, CI actions, and Projects V2 as tools for MCP clients.-
- AlicenseAqualityDmaintenanceGitHub MCP server for Claude Code, Cursor, Cline, Windsurf, and any MCP-compatible client. Exposes GitHub tools (issues, pull requests, code search, file content) to your LLM via the Model Context Protocol.7MIT
- AlicenseNot gradedqualityBmaintenanceA production-grade MCP server that provides LLMs with safe, structured, tool-based access to GitHub repositories, including issue management, semantic search, and guarded write operations.MIT