mcp-server-github
Provides tools for interacting with the GitHub API, enabling management of repositories, issues, pull requests, file contents, code search, branches, and more.
Provides tools for interacting with GitHub Actions workflows and workflow runs.
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., "@mcp-server-githublist my open pull requests"
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.
mcp-server-github
An MCP (Model Context Protocol) server that provides tools for interacting with the GitHub API, including repositories, issues, pull requests, code search, branches, and GitHub Actions workflows.
Architecture
graph TB
subgraph Client
style Client fill:#4A90D9,stroke:#2E6BA6,color:#FFFFFF
MCP_Client["MCP Client"]
end
subgraph Server["mcp-server-github"]
style Server fill:#2ECC71,stroke:#1A9B52,color:#FFFFFF
Index["index.ts<br/>MCP Server Entry"]
subgraph Tools
style Tools fill:#F39C12,stroke:#C67D0A,color:#FFFFFF
T1["list_repos"]
T2["create_issue"]
T3["list_pull_requests"]
T4["get_file_contents"]
T5["search_code"]
T6["create_branch"]
T7["list_workflows"]
T8["get_workflow_runs"]
end
end
subgraph External["GitHub API"]
style External fill:#24292E,stroke:#1B1F23,color:#FFFFFF
Repos["Repos API"]
Issues["Issues API"]
PRs["Pull Requests API"]
Contents["Contents API"]
Search["Search API"]
Git["Git Refs API"]
Actions["Actions API"]
end
MCP_Client -- "stdio transport" --> Index
Index --> T1 & T2 & T3 & T4 & T5 & T6 & T7 & T8
T1 --> Repos
T2 --> Issues
T3 --> PRs
T4 --> Contents
T5 --> Search
T6 --> Git
T7 --> Actions
T8 --> ActionsRelated MCP server: GitHub MCP Server
Installation
npm install
npm run buildConfiguration
Variable | Description | Required |
| GitHub personal access token | Yes |
Usage
Standalone
GITHUB_TOKEN=ghp_xxxx npm startDevelopment
npm run devDocker
docker build -t mcp-server-github .
docker run -e GITHUB_TOKEN=ghp_xxxx mcp-server-githubMCP Client Configuration
{
"mcpServers": {
"github": {
"command": "node",
"args": ["dist/index.js"],
"env": {
"GITHUB_TOKEN": "ghp_xxxx"
}
}
}
}Tool Reference
Tool | Description | Parameters |
| List repositories |
|
| Create an issue |
|
| List pull requests |
|
| Get file contents |
|
| Search code |
|
| Create a branch |
|
| List workflows |
|
| Get workflow runs |
|
License
MIT
Available Tools
8 toolscreate_branchB
Create a new branch in a repository from a source branch
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | Repository owner | |
| repo | Yes | Repository name | |
| branch | Yes | New branch name | |
| from_branch | No | Source branch to branch from (default: main) | main |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits such as idempotency, error handling (e.g., duplicate branch scenario), or required permissions. The description only states the basic intent.
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?
Single sentence with no fluff, clearly communicates the action. Efficiently front-loads the core purpose.
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?
Adequate for a simple creation tool, but lacks discussion of return value, error conditions, or behavior when branch already exists. Leaves gaps for a complete understanding.
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 coverage is 100%, so the baseline is 3. The description adds minimal value beyond the schema; 'from a source branch' is redundant with the default parameter description.
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 verb 'create' and the resource 'branch', and specifies the source branch context. It effectively distinguishes from sibling tools like create_issue.
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 explicit guidance on when to use this tool versus alternatives, or when not to use it. Lacks prerequisites or conditions for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_issueB
Create an issue in a GitHub repository with title, body, labels, and assignees
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | Repository owner | |
| repo | Yes | Repository name | |
| title | Yes | Issue title | |
| body | No | Issue body (Markdown) | |
| labels | No | Labels to apply | |
| assignees | No | Users to assign |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It only states it creates an issue, but gives no info on authentication needs, rate limits, side effects, or what happens on success/failure. Minimal behavioral disclosure.
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?
Single sentence that immediately conveys the core purpose. No extraneous words, perfectly concise and front-loaded.
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 simple creation tool with a well-described schema, the description is nearly complete. It lacks mention of permissions or side effects, but overall it provides sufficient context for an AI agent to understand the tool's function.
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 100%, so baseline is 3. The description briefly lists parameters in prose, but adds no extra meaning beyond the schema's individual descriptions. Adequate, not exceptional.
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 it creates an issue in a GitHub repository and lists the specific fields it handles (title, body, labels, assignees), distinguishing it from sibling tools like create_branch.
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 explicit guidance on when to use this tool versus alternatives, no prerequisites mentioned, and no conditions under which it should not be used. The sibling tools are different, but the description lacks usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_file_contentsB
Get file or directory contents from a GitHub repository
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | Repository owner | |
| repo | Yes | Repository name | |
| path | Yes | File path in the repository | |
| ref | No | Git ref (branch, tag, or SHA) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states 'Get file or directory contents' but omits details such as how content is returned (e.g., raw, base64), behavior for large files, or error conditions.
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 a single concise sentence that front-loads the key action and resource, with no unnecessary words.
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 read tool with no output schema, the description does not explain return values. It covers the basic action but lacks details on what the output contains (e.g., raw content vs. metadata). It is minimally adequate but not 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?
Schema coverage is 100%, so baseline is 3. The description adds the nuance of 'directory' beyond the schema's 'File path', but does not elaborate on parameter formats 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 verb 'Get' and the resource 'file or directory contents from a GitHub repository'. It accurately reflects the tool's function and distinguishes it from sibling tools like create_branch or create_issue.
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, when not to, or alternatives. It simply states the action without context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_workflow_runsB
Get workflow run history for a specific GitHub Actions workflow
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | Repository owner | |
| repo | Yes | Repository name | |
| workflow_id | Yes | Workflow ID | |
| status | No | Filter by run status |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states 'Get workflow run history' without disclosing behavioral traits like read-only nature, pagination, rate limits, or any side effects. For a get operation, the safety is implied but not explicitly stated.
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 a single sentence that is efficiently worded and front-loaded. It conveys the core purpose without any wasted words.
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?
The tool has no output schema, so the description should address return values or result format. It does not. Additionally, behavioral transparency is lacking, making the description incomplete for an AI agent to fully understand the tool's output and behavior.
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 coverage is 100%, so the schema already documents all four parameters. The description adds no extra meaning beyond what the parameter descriptions in the schema provide. Baseline score of 3 is appropriate.
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 specifies the verb 'get' and the resource 'workflow run history for a specific GitHub Actions workflow'. It distinguishes from siblings like list_workflows which list workflows, not specific run histories. This is specific and helpful.
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 such as list_workflows (which lists workflows) or other sibling tools. There are no explicit use cases, conditions, or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_pull_requestsA
List pull requests in a repository with optional state and sort filters
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | Repository owner | |
| repo | Yes | Repository name | |
| state | No | PR state filter | open |
| sort | No | Sort field |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It indicates the tool is read-only (list operation) but does not mention pagination, rate limits, or authentication. The description is minimal, scoring 3 as it adds no behavioral context beyond the obvious.
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 a single concise sentence that directly states the tool's purpose and key options. It is front-loaded and contains no unnecessary words, earning a 5.
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 is simple (4 parameters, no output schema) and the description covers the main functionality, it is fairly complete. It could mention pagination or result format, but for a straightforward list operation, the description suffices. Score 4.
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 100%, so the schema already documents all parameters. The description adds no additional meaning beyond what the schema provides, just restating 'optional state and sort filters'. Baseline 3 is appropriate.
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 lists pull requests in a repository with optional state and sort filters. It uses a specific verb ('List') and resource ('pull requests in a repository'), and provides enough detail to distinguish from sibling tools like create_branch or create_issue.
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 implies usage for listing pull requests but does not provide explicit guidance on when to use this tool versus alternatives. No exclusions or comparisons with other list tools are given, so it is adequate but lacks depth.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_reposC
List repositories for a user, organization, or the authenticated user
| Name | Required | Description | Default |
|---|---|---|---|
| owner | No | Repository owner (user or org). If omitted, lists repos for the authenticated user. | |
| type | No | Type filter | |
| sort | No | Sort field |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits beyond listing. It does not mention that the operation is read-only, nor does it discuss rate limits, authentication requirements, or pagination. The behavior of omitting the owner parameter is described in the schema, but not reiterated in the description.
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 a single sentence with 9 words, containing no unnecessary information. It is front-loaded and efficiently conveys the core purpose.
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?
The tool is simple, but the description lacks details about return values, pagination, or behavioral expectations. Without an output schema, the description should provide more context for an agent to understand what the tool returns and how to handle it.
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 input schema has 100% description coverage for all three parameters. The description adds no additional meaning beyond what the schema already provides, so it meets the baseline for this dimension.
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 action ('List repositories') and the scoping options ('for a user, organization, or the authenticated user'). It distinguishes the tool from sibling tools that perform other actions like creating branches or issues, but does not explicitly contrast them.
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 does not mention specific contexts, prerequisites, or situations where a different tool would be more appropriate. Sibling tools such as 'list_pull_requests' are not referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_workflowsB
List GitHub Actions workflows in a repository
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | Repository owner | |
| repo | Yes | Repository name |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations and description only says 'List...', omitting behavioral traits such as read-only nature, pagination, or rate limits. Agent lacks safety context.
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?
Single sentence, front-loaded with key action and resource, zero wasted words.
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?
Simple tool with 2 parameters and no output schema; description is adequate but lacks details like return format or pagination behavior, leaving some gaps.
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 covers 100% of parameters with descriptions. Description adds no extra meaning beyond schema, meeting baseline with no enhancement.
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 it lists GitHub Actions workflows in a repository, using specific verb 'List' and resource 'GitHub Actions workflows'. It distinguishes from sibling 'get_workflow_runs' by focusing on workflows vs runs.
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 on when to use this tool versus alternatives like 'get_workflow_runs'. No context about prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_codeB
Search code across GitHub repositories using GitHub search syntax
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query (GitHub code search syntax) | |
| per_page | No | Results per page (max 100) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as rate limits, authentication requirements, pagination behavior, or what happens on no results. The minimal description fails to inform the agent of important operational aspects.
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 a single sentence that directly states the tool's purpose with no unnecessary words or redundancy.
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 lack of output schema and minimal description, the tool's documentation is incomplete. It doesn't explain what the search returns, how to interpret results, or any nuances of GitHub code search syntax.
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 coverage is 100% with both parameters having descriptions. The tool description adds no additional meaning beyond what the schema provides, so baseline 3 is appropriate.
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 'Search code across GitHub repositories using GitHub search syntax', specifying the verb 'Search', the resource 'code', and the scope 'across GitHub repositories'. It distinguishes from sibling tools like create_branch or get_file_contents, which are mutation or retrieval tools.
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 does not mention scenarios where get_file_contents or list_repos would be more appropriate, nor does it specify limitations or prerequisites.
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.
8 tool updates
v1.0.0- First observed
create_branch - First observed
create_issue - First observed
get_file_contents - First observed
get_workflow_runs - First observed
list_pull_requests - First observed
list_repos - First observed
list_workflows - First observed
search_code
TDQS
Each tool targets a distinct GitHub resource or action: branches, issues, file contents, workflow runs, pull requests, repos, workflows, and code search. No overlap in purpose.
All tool names use a consistent verb_noun pattern in snake_case (e.g., create_branch, list_pull_requests), making them predictable and easy to interpret.
With 8 tools, the set is well-scoped for a GitHub MCP server, covering essential read operations and some write operations without being bloated.
Missing critical operations like updating or closing issues, creating or merging pull requests, and managing repositories. The surface has notable gaps for typical GitHub workflows.
Maintenance
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
Access the GitHub API, enabling file operations, repository management, search functionality, and…
Manage repositories, users, releases, and automate GitHub workflows
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables interaction with GitHub repositories through the GitHub API, allowing file operations, repository management, issue tracking, and code search through natural language commands.33154MIT
- FlicenseNot gradedqualityCmaintenanceEnables access to GitHub repositories and data through the GitHub API. Supports retrieving repositories, issues, pull requests, and searching code across GitHub with authentication via personal access tokens.-
- AlicenseNot gradedqualityNot gradedmaintenanceEnables comprehensive interaction with GitHub repositories, including code management, issues, pull requests, and full GitHub Actions workflow control with triggering, monitoring, and artifact management capabilities.118-
- AlicenseNot gradedqualityDmaintenanceEnables comprehensive interaction with the GitHub API for managing repositories, issues, pull requests, commits, and GitHub Actions workflows through natural language.118MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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/Citadel-Cloud-Management/mcp-server-github'
If you have feedback or need assistance with the MCP directory API, please join our Discord server