Skip to main content
Glama
promplate

gh-mcp

by promplate
OverviewSchemaRelated ServersScoreDiscussions
Python

Refined MCP server for GitHub

TIP

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:

  1. Powerful interfaces — exposes GraphQL and Code Search instead of atomized endpoints. LLMs already understand these APIs.

  2. YAML output — makes nested data and file content readable without escaping.

  3. Clean abstractions — gh handles authentication and low-level details. And LLMs know how to use its --jq option to filter.

Swapping in gh-mcp delivers better performance at lower cost for any GitHub interactions.

Installation

with uv:

uvx mcp-hmr

MCP config:

{
    "mcpServers": {
        "gh": {
            "command": "uvx",
            "args": ["gh-mcp"]
        }
    }
}

If you prefer serving it via streamable-http:

uvx gh-mcp --http
NOTE

This 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 tools
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:

  1. You know the files are not too many.

  2. The user specifically requests it.

  3. 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.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
jqNo def process: if type == "object" then if has("text") and (.text | type == "string") then if (.text | split("\n") | length) > 10 then del(.text) + {lines: (.text | split("\n") | to_entries | map("\(.key + 1): \(.value)") | join("\n"))} else . end else with_entries(.value |= process) end elif type == "array" then map(process) else . end; .data | process

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite no annotations, the description thoroughly explains behavioral aspects: GraphQL capabilities, introspection, combining operations, jq processing, error handling, deep links, and efficiency principles.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very long with extensive examples and detail. While valuable, it lacks conciseness; a more front-loaded structure with optional examples would improve readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, no output schema, and zero schema description coverage, the description provides complete context: usage, error handling, jq, introspection, combination strategies, and deep links. It is highly comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by explaining the 'query' parameter's purpose and the 'jq' param's default behavior, including examples of jq usage and output transformation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it executes GitHub GraphQL queries and mutations, and explicitly distinguishes itself from raw CLI calls and other tools. It is specific and action-oriented.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides explicit when-to-use guidance (keywords like find/search/read, etc.), states its preference over alternatives, and includes when-not-to-use (recursive file fetch conditions).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev1.0.0
    • Changedgithub_code_search1 field changed
      • changedInput schema / properties / code_snippet / description
        Previous value: -"Not a fuzzy search. Grep exact code snippet you want to find. Modifiers or wildcards not supported."New value: +"Search exact string you want to find. DO NOT use any wildcard syntax."
  2. 2 tool updates
    • First observedgithub_code_search
    • First observedgithub_graphql
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0
Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count3/5

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.

Completeness2/5

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

ActivityMaintained
ResponsivenessUnresponsive

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • epik-gh

    epik-agent
    F
    license
    Not graded
    quality
    B
    maintenance
    A 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.
    -

  • github-mcp

    AbdeeBuilds
    A
    license
    A
    quality
    C
    maintenance
    GitHub 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.
    7
    MIT

  • GitHub MCP Toolkit

    kartik-012
    A
    license
    Not graded
    quality
    B
    maintenance
    A 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

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/promplate/refined-mcp-servers'

If you have feedback or need assistance with the MCP directory API, please join our Discord server