Skip to main content
Glama

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 --> Actions

Related MCP server: GitHub MCP Server

Installation

npm install
npm run build

Configuration

Variable

Description

Required

GITHUB_TOKEN

GitHub personal access token

Yes

Usage

Standalone

GITHUB_TOKEN=ghp_xxxx npm start

Development

npm run dev

Docker

docker build -t mcp-server-github .
docker run -e GITHUB_TOKEN=ghp_xxxx mcp-server-github

MCP Client Configuration

{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxx"
      }
    }
  }
}

Tool Reference

Tool

Description

Parameters

list_repos

List repositories

owner?, type?, sort?

create_issue

Create an issue

owner, repo, title, body?, labels?, assignees?

list_pull_requests

List pull requests

owner, repo, state?, sort?

get_file_contents

Get file contents

owner, repo, path, ref?

search_code

Search code

query, per_page?

create_branch

Create a branch

owner, repo, branch, from_branch?

list_workflows

List workflows

owner, repo

get_workflow_runs

Get workflow runs

owner, repo, workflow_id, status?

License

MIT

Available Tools

8 tools
create_branchB

Create a new branch in a repository from a source branch

ParametersJSON Schema
NameRequiredDescriptionDefault
ownerYesRepository owner
repoYesRepository name
branchYesNew branch name
from_branchNoSource branch to branch from (default: main)main

TDQS

B3.3/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
ownerYesRepository owner
repoYesRepository name
titleYesIssue title
bodyNoIssue body (Markdown)
labelsNoLabels to apply
assigneesNoUsers to assign

TDQS

B3.4/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
ownerYesRepository owner
repoYesRepository name
pathYesFile path in the repository
refNoGit ref (branch, tag, or SHA)

TDQS

B3.3/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
ownerYesRepository owner
repoYesRepository name
workflow_idYesWorkflow ID
statusNoFilter by run status

TDQS

B3.2/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
ownerYesRepository owner
repoYesRepository name
stateNoPR state filteropen
sortNoSort field

TDQS

A3.8/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
ownerNoRepository owner (user or org). If omitted, lists repos for the authenticated user.
typeNoType filter
sortNoSort field

TDQS

C2.9/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
ownerYesRepository owner
repoYesRepository name

TDQS

B3.3/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSearch query (GitHub code search syntax)
per_pageNoResults per page (max 100)

TDQS

B3.2/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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.

  1. 8 tool updatesv1.0.0
    • First observedcreate_branch
    • First observedcreate_issue
    • First observedget_file_contents
    • First observedget_workflow_runs
    • First observedlist_pull_requests
    • First observedlist_repos
    • First observedlist_workflows
    • First observedsearch_code

TDQS

A3.5/5.0
Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count5/5

With 8 tools, the set is well-scoped for a GitHub MCP server, covering essential read operations and some write operations without being bloated.

Completeness2/5

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

ActivityInactive
ResponsivenessSyncing

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

  • F
    license
    Not graded
    quality
    C
    maintenance
    Enables 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.
    -
  • A
    license
    Not graded
    quality
    Not graded
    maintenance
    Enables 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
    -

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/Citadel-Cloud-Management/mcp-server-github'

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