Uses .env files to securely store GitHub access tokens needed for API authentication.
Enables querying GitHub's GraphQL API to retrieve repository information, issues, pull requests, user profiles, and project dependencies with precise data control to reduce token consumption.
Provides schema exploration and query execution capabilities for GitHub's GraphQL API, allowing for precise data retrieval through query customization.
Click on "Install 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., "@GitHub GraphQL API MCP get the latest issues and pull requests for the claude-desktop 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.
English | 中文 | 日本語 | Español | Français
A tool based on MCP (Model Context Protocol) for querying and using the GitHub GraphQL API. This project provides a server that allows you to explore the GitHub GraphQL schema and execute GraphQL queries through MCP client tools (such as Claude AI).
Related MCP server: @cloud9-labs/mcp-github
GitHub GraphQL API offers significant advantages over traditional REST APIs:
Precise Data Retrieval: GraphQL allows clients to specify exactly which fields they need, avoiding excess data
Reduced Token Consumption: By requesting only necessary fields, API response size is significantly reduced, lowering AI model token consumption
Single Request for Related Data: One query can retrieve multiple related resources, reducing the number of requests
Self-Documenting: Through its built-in documentation system, you can directly query and understand the API schema without external documentation
Strong Type System: Provides type checking, reducing errors
This project leverages these advantages to provide tools that help you effectively explore the GitHub GraphQL API schema and execute optimized queries, providing AI assistants with efficient GitHub data retrieval capabilities.
This tool easily implements the following common operations:
Repository Basic Information Query: Get repository name, description, star count, branch list, and other basic information
Issue Data Retrieval: Query issue lists, details, or comment content for specific repositories
User Profile Access: Retrieve users' personal profiles, contribution statistics, and other public information
Pull Request Status View: Get PR basic status, comment content, and merge information
Project Dependency Query: Retrieve project dependency package lists and version information
With GraphQL's flexible query capabilities, you can also try to implement the following advanced analysis functions:
Repository Contribution Trend Analysis: Analyze code update frequency and contributor participation by aggregating commit data, evaluating project activity
Issue Management and Classification: Organize issue data according to custom conditions, discover problems that need priority handling, and improve project management efficiency
Code Review Pattern Analysis: Analyze PR comments and review processes, identify common problem patterns, and optimize code review workflow
Contributor Network Visualization: Build collaboration relationships between project contributors, discover key contributors and areas of expertise
Dependency Health Assessment: Evaluate the update frequency and potential security issues of project dependencies, providing dependency management suggestions
Query GitHub GraphQL schema root types (Query/Mutation)
Get detailed documentation for specific types
Query documentation and parameters for specific fields
Execute GitHub GraphQL API queries directly, precisely retrieving needed data, reducing token consumption
Multilingual support (English/Chinese/Japanese/Spanish/French)
Compared to the official github-mcp-server, this project offers distinct advantages in specific scenarios:
Feature | GitHub GraphQL API MCP | Official GitHub MCP Server |
Core Mechanism | Single GraphQL Query | Multiple REST API / Granular Tools |
Data Retrieval | One-shot: Fetch repository details, issues, PRs, history, and releases in a single request | Multi-step: Requires chaining |
Efficiency | High. Minimizes network latency and round-trips. | Lower for complex data gathering. High latency due to sequential tool calls. |
Token Usage | Optimized. Returns only requested fields. | Higher. Intermediate tool outputs (full JSON responses) consume context window. |
Flexibility | High. Client defines exact data structure needed. | Fixed. Client must work with predefined API response structures. |
API Coverage | Complete. Access any field exposed by GitHub's GraphQL API. | Partial. Limited to the specific REST endpoints hardcoded by the maintainers. |
Introspection | Built-in. AI can query the schema to learn about new API fields dynamically. | None. AI relies on its training data; cannot discover new API features without tool updates. |
Maintainability | Zero-code updates. Often just requires a schema file update to support new GitHub features. | Code-heavy. Requires writing new Go handlers and struct definitions for every new feature. |
Complexity | Requires LLM to write GraphQL (supported by schema introspection tools). | Easier for LLMs that prefer simple function calls, but harder to manage state across calls. |
Example: To get "latest important updates for a project", this tool can fetch releases, recent commits, and open issues in one go, whereas the official server might require 5+ separate tool calls and round trips.
Context Window Efficiency: Official tools often return massive JSON objects (e.g., a full repository object might be 5KB+). With GraphQL, you fetch only the name and description, saving 99% of tokens.
Complex Reasoning: AI agents often need to traverse relationships (e.g., "Find the author of the PR that closed this Issue"). In REST/Official tools, this is a multi-step "Search -> Get ID -> Get PR -> Get Author" process. In GraphQL, it's a single nested query, allowing the AI to focus on reasoning rather than data plumbing.
Future Proofing: When GitHub adds a new feature (e.g., a new field on Discussions), this MCP server can support it immediately via schema introspection, while the official server waits for a code update.
Python 3.10 or higher
GitHub personal access token (for accessing the GitHub API)
Poetry (recommended dependency management tool)
We recommend using uv for management, which is currently the fastest and simplest Python project management tool. Alternatively, you can use standard pip.
With uv, you don't need to manually create virtual environments or install dependencies; it handles everything for you automatically.
Install uv (Skip if already installed):
# MacOS / Linux
curl -lsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"Configure Environment Variables:
Copy .env.example to .env and fill in your GitHub Token:
cp .env.example .env
# Edit .env file and fill in your tokenOne-click Run:
uv run github_graphql_api_mcp_server.pyuv will automatically create a virtual environment, download and install all dependencies, and then start the server.
If you prefer not to install extra tools, you can use the traditional Python method:
Create and Activate Virtual Environment:
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activateInstall Dependencies:
pip install -r requirements.txtConfigure Environment Variables:
Create and configure .env file as above.
Run:
python github_graphql_api_mcp_server.pyYou can configure this MCP server in the Claude desktop app for one-click startup:
Open the Claude desktop app
Go to settings, find the MCP server configuration section
Add the following configuration (modify according to your actual path):
{
"mcpServers": {
"github_mcp": {
"command": "/path/to/uv",
"args": [
"run",
"--directory",
"<project path>",
"github_graphql_api_mcp_server.py"
]
}
}
}Configuration example (using uv):
{
"mcpServers": {
"github_mcp": {
"command": "/Users/username/.cargo/bin/uv",
"args": [
"run",
"--directory",
"/Users/username/github/github_graphql_api_mcp/",
"github_graphql_api_mcp_server.py"
]
}
}
}If using standard Python (Method 2):
{
"mcpServers": {
"github_mcp": {
"command": "/path/to/project/.venv/bin/python",
"args": [
"github_graphql_api_mcp_server.py"
]
}
}
}After configuration, you can start the MCP server directly from the Claude desktop app without having to start it manually.
The server provides the following tools:
print_type_field: Query fields of GitHub GraphQL schema root types
graphql_schema_root_type: Get documentation for root types (Query/Mutation)
graphql_schema_type: Query documentation for specific types
call_github_graphql: Execute GitHub GraphQL API queries
After connecting to the server with an MCP client, you can:
Query root type documentation:
Use the graphql_schema_root_type tool, parameter type_name="QUERY"Query fields of specific types:
Use the print_type_field tool, parameters type_name="QUERY", type_fields_name="repository"Query documentation for specific types:
Use the graphql_schema_type tool, parameter type_name="Repository"Execute GraphQL queries:
Use the call_github_graphql tool, parameter:
graphql="""
query {
viewer {
login
name
}
}
"""Below is an example of using the GitHub GraphQL API MCP with Claude:
Make sure your GitHub token has appropriate permissions before use
The token is stored in the .env file, which should not be committed to version control systems
Queries should comply with GitHub API usage limits
This project is licensed under the MIT License - a very permissive license that allows users to freely use, modify, distribute, and commercialize this software, as long as they retain the copyright notice and license statement.
See MIT License for detailed terms.
A tool to execute GitHub GraphQL API queries. Before using, it's recommended to check the documentation first, and include ID fields in your queries for easier follow-up operations Args: graphql: The GraphQL query Returns: str: Execution result
| Name | Required | Description | Default |
|---|---|---|---|
| graphql | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions checking documentation and including ID fields, which adds some operational context, but fails to address critical traits like authentication requirements, rate limits, error handling, or mutation vs. query behavior. For a GraphQL API tool with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves in practice.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, starting with the core purpose and usage recommendation in the first sentence. The Args and Returns sections are structured but could be more integrated. There's minimal waste, though the 'Returns: str: Execution result' is redundant given the output schema, slightly reducing efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (GraphQL API execution) and the presence of an output schema (which handles return values), the description is partially complete. It covers basic purpose and some usage tips but lacks details on authentication, error cases, or integration with sibling tools. Without annotations and with low schema coverage, it doesn't fully equip an agent for reliable tool invocation in a GitHub context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds minimal meaning beyond the input schema: it names the single parameter 'graphql' and states it's 'The GraphQL query', which the schema already indicates as a string type. With 0% schema description coverage, the description doesn't compensate by explaining query syntax, validation rules, or examples. The baseline is 3 because the schema covers the parameter's existence and type, but the description fails to enhance understanding significantly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as 'execute GitHub GraphQL API queries' with a specific verb (execute) and resource (GitHub GraphQL API queries). It distinguishes itself from sibling tools like graphql_schema_root_type and graphql_schema_type by focusing on query execution rather than schema exploration. However, it doesn't explicitly contrast with print_type_field, leaving some sibling differentiation incomplete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implied usage guidance by recommending checking documentation first and including ID fields for follow-up operations, which suggests context for when to use this tool effectively. However, it lacks explicit when/when-not criteria or named alternatives to sibling tools, leaving the agent to infer optimal usage scenarios without clear boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A tool to query GitHub GraphQL schema root types. You need to provide the root type name (QUERY/MUTATION) Args: type_name: root type (QUERY or MUTATION) Returns: str: Documentation content
| Name | Required | Description | Default |
|---|---|---|---|
| type_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral context. It states the tool returns documentation content as a string but doesn't disclose authentication requirements, rate limits, error handling, or what specific documentation format to expect. The 'query' verb implies read-only, but this isn't explicitly confirmed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with three sentences: purpose statement, parameter guidance, and return value. It's front-loaded with the core function. Minor improvements could include bullet points for Args/Returns, but overall it's efficient with minimal waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, no output schema, and low schema coverage, the description is incomplete. It lacks details on authentication, error cases, the structure of returned documentation, or how this integrates with sibling tools. The return type 'str: Documentation content' is vague without examples or format specifications.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by explaining that 'type_name' should be 'QUERY or MUTATION' and represents the 'root type name.' This adds meaningful context beyond the schema's generic 'Type Name' title, though it doesn't detail format constraints or examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as 'query GitHub GraphQL schema root types' with specific resource (GitHub GraphQL schema) and verb (query). It distinguishes from sibling 'graphql_schema_type' by focusing on root types only, though it doesn't explicitly contrast with 'call_github_graphql' or 'print_type_field'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'graphql_schema_type' for non-root types or 'call_github_graphql' for actual queries. The description mentions needing to provide root type name but doesn't explain use cases or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A tool to query specific type documentation in GitHub GraphQL schema. You need to provide the type_name
Args:
type_name: Type name like SecurityAdvisoryConnection
Returns:
str: Documentation content
| Name | Required | Description | Default |
|---|---|---|---|
| type_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool queries documentation, implying a read-only operation, but doesn't specify if it's safe, requires authentication, has rate limits, or what happens on errors. For a query tool with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded: the first sentence states the purpose clearly. The 'Args:' and 'Returns:' sections are structured but slightly redundant with the schema. It's concise with no wasted words, though the formatting could be more integrated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is somewhat complete but has gaps. It covers the basic purpose and parameter semantics but lacks usage guidelines, behavioral details, and output explanation. For a simple query tool, it's adequate but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate. It explains the single parameter 'type_name' as 'Type name like `SecurityAdvisoryConnection`,' adding meaning beyond the schema's basic 'string' type. This clarifies the parameter's purpose and provides an example, though it could be more detailed about valid type names or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'query specific type documentation in GitHub GraphQL schema.' It specifies the verb ('query'), resource ('type documentation'), and domain ('GitHub GraphQL schema'). However, it doesn't explicitly differentiate from sibling tools like 'graphql_schema_root_type' or 'print_type_field' beyond mentioning 'specific type' documentation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal guidance: 'You need to provide the type_name' and gives an example ('SecurityAdvisoryConnection'). It doesn't explain when to use this tool versus alternatives like 'graphql_schema_root_type' or 'print_type_field,' nor does it mention prerequisites or exclusions. The guidance is basic and lacks context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A tool to query GitHub GraphQL schema root type fields. You need to provide root_type_name and type_fields_name
Args:
type_name: root type like QUERY or MUTATION
type_fields_name: field name like repository based on root type documentation
Returns:
str: Documentation content for the specified field
| Name | Required | Description | Default |
|---|---|---|---|
| type_name | Yes | ||
| type_fields_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool returns documentation content as a string, which is useful behavioral information. However, it doesn't mention whether this is a read-only operation, what happens with invalid inputs, if there are rate limits, authentication requirements, or error behavior. For a query tool with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise but has structural issues. The first sentence clearly states the purpose, but the parameter explanations are formatted as 'Args:' and 'Returns:' sections which are somewhat redundant with the schema. The information is front-loaded but could be more efficiently integrated. It's not excessively verbose but has minor organizational inefficiencies.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 parameters with 0% schema coverage and no output schema, the description provides adequate parameter semantics and specifies the return type as a string. However, it doesn't explain the format of the returned documentation content, error conditions, or authentication requirements. For a query tool with no annotations, this is minimally complete but lacks depth about operational behavior and integration context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides meaningful semantics for both parameters: 'type_name' is explained as 'root type like `QUERY` or `MUTATION`' and 'type_fields_name' as 'field name like `repository` based on root type documentation'. This adds substantial value beyond the bare schema, though it doesn't provide exhaustive examples or format details. With 2 parameters fully addressed, this exceeds the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'query GitHub GraphQL schema root type fields' with specific verbs ('query') and resources ('GitHub GraphQL schema root type fields'). It distinguishes from siblings like 'call_github_graphql' (which executes queries) and 'graphql_schema_type' (which might query non-root types), but doesn't explicitly contrast them. The purpose is specific but sibling differentiation is implied rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It mentions 'based on root type documentation' but doesn't specify when this tool is appropriate compared to sibling tools like 'graphql_schema_root_type' or 'graphql_schema_type'. There are no explicit when/when-not instructions or named alternatives, leaving usage context unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
call_github_graphqlgraphql_schema_root_typegraphql_schema_typeprint_type_fieldThe tools have overlapping purposes focused on GitHub GraphQL schema exploration, which could cause confusion. call_github_graphql is distinct for executing queries, but graphql_schema_root_type, graphql_schema_type, and print_type_field all retrieve schema documentation with subtle differences in scope (root types vs. specific types vs. root type fields). Descriptions help clarify, but an agent might struggle to choose between them for schema inspection tasks.
Tool names follow a consistent snake_case pattern with clear verb_noun structure (e.g., call_github_graphql, graphql_schema_type). Minor deviations exist, such as graphql_schema_root_type using 'root_type' while print_type_field uses 'type_field', but overall the naming is predictable and readable across all tools.
With 4 tools, the count is reasonable for a GitHub GraphQL API server, providing a focused set for query execution and schema exploration. It's slightly thin for comprehensive API coverage but well-scoped for its intended purpose, avoiding bloat while supporting core workflows like querying and schema lookup.
The tool set covers query execution and schema documentation retrieval, but has notable gaps for a GitHub API surface. It lacks CRUD operations for resources like repositories, issues, or pull requests, and doesn't support mutations or advanced query building. Agents can work around this by crafting GraphQL queries, but the surface is incomplete for typical GitHub automation tasks.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
The Grafbase MCP server sits in front of a GraphQL API and exposes an MCP protocol-compliant interface that allows AI agents and LLMs to explore and query GraphQL APIs using natural language. It provides tools to search schemas, introspect types and fields, and execute GraphQL queries while minimizing context bloat by returning only relevant schema subsets, with built-in support for authentication, authorization, and configurable access control.
An MCP server that gives your AI access to the source code and docs of all public github repos
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
Token-free MCP server for structured RevoGrid Core, Pro, and Enterprise knowledge retrieval.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/wanzunz/github_graphql_api_mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
