github-ops-mcp
Allows searching GitHub repositories, retrieving repository metadata and statistics, cloning repos into a sandboxed workspace, and performing read-only git operations such as listing branches, commits, diffs, issues, and pull requests.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@github-ops-mcp What are the open PRs on facebook/react?"
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.
github-ops-mcp
A small MCP server that lets an LLM (Claude Desktop, Claude Code, or any MCP client) search GitHub, clone repos into a sandboxed workspace, and run common read-only git / gh operations. Personal project — see plan.md for the design.
1. Prerequisites
Make sure these are installed and working before you continue:
git --version # any recent git
gh --version # GitHub CLI — https://cli.github.com/
python3 --version # Python 3.11 or newerLog in to GitHub once (opens a browser):
gh auth loginVerify:
gh auth statusRelated MCP server: GitHub MCP Agent Server
2. Install
git clone <this-repo> github_operation_mcp
cd github_operation_mcp
# Create a virtualenv (any Python 3.11+ works; example uses 3.14)
python3 -m venv .venv
source .venv/bin/activate
# Install the package + its one dependency (mcp SDK, pinned to v1.x)
pip install --upgrade pip
pip install -e .3. Run the server
Option A — stdio (for Claude Desktop / Claude Code)
python -m github_ops_mcp.server --stdioYou normally don't run this by hand — Claude Desktop launches it for you via the config in step 4.
Option B — HTTP / SSE (for remote clients / demos)
python -m github_ops_mcp.server --http --host 0.0.0.0 --port 8000The MCP endpoint is then at http://<host>:8000/mcp.
4. Wire it into Claude Desktop
Edit (or create) the config file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Add this entry (replace the two paths with your absolute paths):
{
"mcpServers": {
"github-ops": {
"command": "/Users/YOU/Documents/github_operation_mcp/.venv/bin/python",
"args": ["-m", "github_ops_mcp.server", "--stdio"],
"env": {
"WORKSPACE_ROOT": "/Users/YOU/Documents/github_operation_mcp/test_repos"
}
}
}
}Then fully quit Claude Desktop (Cmd+Q, not just close the window) and reopen it. You should see 25 tools appear under the github-ops server.
WORKSPACE_ROOT— optional. Everyclone_repocall lands under this directory as<owner>__<repo>/. If you omit it, the server defaults to aworkspace/folder next to the package.
5. Wire it into Claude Code
Either add the same block to a .mcp.json at the project root, or run:
claude mcp add github-ops \
/Users/YOU/Documents/github_operation_mcp/.venv/bin/python \
-- -m github_ops_mcp.server --stdio6. Try it
In Claude Desktop:
"Search for repositories about MCP servers" →
search_repos"Give me a full summary of
modelcontextprotocol/python-sdk" →generate_repo_summary"Clone
octocat/Hello-World" →clone_repo"What branches does it have?" →
list_branches"Show me the last 5 commits" →
list_commits"Any open PRs on
facebook/react?" →list_pull_requests
Tools (25)
Discovery —
search_repos,get_repo_info,summarize_readmeRepo stats —
get_repo_stats,get_contributors,get_language_breakdown,get_topics,get_license,get_releasesStretch stats —
get_default_branch_protection,get_commit_activity,get_network_infoComposite —
generate_repo_summarySetup —
clone_repo,pull_latestBranches —
list_branches,checkout_branch,list_commits,get_file_historyComparison —
get_status,get_diff,compare_branchesIssues & PRs —
list_open_issues,list_pull_requests,get_pr_diff
Every tool returns { ok: bool, data: ..., error: ... }.
Safety
All clones live under
WORKSPACE_ROOT(./workspace/by default). Path traversal (../) is blocked.gitandghsubcommands are whitelisted. Destructive commands (push,reset --hard,rebase,clean,branch -D,gh repo delete/edit, …) raisePermissionError.gh apicalls are restricted torepos/...endpoints.User inputs are passed as argv items, never shell-interpolated (
shell=False).Auth is not handled by this server — it relies on your existing
gh auth loginsession and git credentials.
Troubleshooting
Claude Desktop log shows
Read-only file system: '/workspace'— you're on an older build; pull latest, the default workspace now anchors to the package directory instead of the CWD.Every tool call errors with
unexpected keyword argument 'args'— you're on an older build;functools.wrapsis now used so FastMCP sees the real parameter names. Pull latest.gh: To get started with GitHub CLI, please run: gh auth login— rungh auth loginfrom a terminal, then restart Claude Desktop.Server doesn't appear in Claude Desktop — check the log at
~/Library/Logs/Claude/mcp-server-github-ops.log. Common issues: wrong Python path in the config, virtualenv not activated when you ranpip install -e ..
Layout
github_operation_mcp/
├── pyproject.toml
├── README.md
├── plan.md
├── test_repos/ # cloned repos land here (gitignored)
└── src/github_ops_mcp/
├── server.py # FastMCP app + --stdio/--http entrypoint
├── config.py # WORKSPACE_ROOT, timeouts
├── validators.py # owner_repo + branch name checks
├── sandbox.py # path resolution + traversal guard
├── git_wrapper.py # git subprocess wrapper (whitelist)
├── gh_wrapper.py # gh subprocess wrapper (whitelist)
└── tools/
├── discovery.py
├── setup.py
├── branches.py
├── comparison.py
├── issues_prs.py
├── repo_stats.py
├── repo_stats_ext.py
└── repo_summary.pyAvailable Tools
25 toolscheckout_branchC
Switch to a branch, optionally creating it.
Inputs: branch (required), repo_path (required), create_new.
clone_repoB
Clone a repo into the sandboxed workspace (no-op if already cloned).
Inputs: owner_repo (required).
compare_branchesB
Ahead / behind counts between two branches.
Inputs: branch_a (required), branch_b (required), repo_path (required).
generate_repo_summaryB
Aggregate stats + contributors + languages + topics + license + latest release + README.
Inputs: owner_repo (required).
get_commit_activityC
Weekly commit counts over the last year.
Inputs: owner_repo (required).
get_contributorsB
Top contributors by commit count.
Inputs: owner_repo (required), limit.
get_default_branch_protectionA
Branch protection status on the default branch. Requires admin — falls back to 'unknown'.
Inputs: owner_repo (required).
get_diffC
Diff between two branches or commits.
Inputs: base (required), head (required), repo_path (required).
get_file_historyB
Commit history for a specific file (follows renames).
Inputs: filepath (required), repo_path (required).
get_language_breakdownD
Language usage as percentages of bytes.
Inputs: owner_repo (required).
get_licenseC
License name for the repo.
Inputs: owner_repo (required).
get_network_infoC
List of forks with owner and star counts.
Inputs: owner_repo (required), limit.
get_pr_diffC
Return the raw diff for a given PR.
Inputs: pr_number (required), owner_repo (required).
get_releasesC
Latest release plus recent release/tag history.
Inputs: owner_repo (required), limit.
get_repo_infoC
Fetch quick metadata for a repo.
Inputs: owner_repo (required).
get_repo_statsC
Stars, forks, watchers, open issue/PR counts, size, timestamps.
Inputs: owner_repo (required).
get_statusB
Working-tree status split into staged / unstaged / untracked.
Inputs: repo_path (required).
get_topicsD
Repo topics/tags.
Inputs: owner_repo (required).
list_branchesA
List all local and remote branches, plus the current one.
Inputs: repo_path (required).
list_commitsB
Show the last N commits.
Inputs: repo_path (required), n.
list_open_issuesC
List open issues, optionally filtered by label.
Inputs: owner_repo (required), label.
list_pull_requestsC
List open PRs with CI check status.
Inputs: owner_repo (required).
pull_latestB
Run git pull in an already-cloned repo.
Inputs: repo_path (required).
search_reposA
Search GitHub for repositories matching a keyword.
Inputs: query (required), limit.
summarize_readmeA
Return the README text (truncated) so the caller can summarize it.
Inputs: owner_repo (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 25 tools
Most tools have clearly distinct purposes (e.g., get_contributors vs get_language_breakdown). Some overlap exists between get_repo_info, get_repo_stats, and generate_repo_summary, but descriptions clarify their roles. get_diff and get_pr_diff are similar but context-specific.
Tools consistently use snake_case verb_noun patterns like list_, get_, search_, clone_, checkout_. Minor deviations like pull_latest are still readable and do not break the overall pattern.
25 tools is at the upper edge of the borderline range. While many are focused, there is redundancy (e.g., get_repo_info and get_repo_stats could be consolidated), making the set feel heavier than necessary.
The server provides extensive read-only repo metadata and local git operations, but lacks write operations like creating/updating issues or PRs, and lacks push/commit capabilities. This leaves notable gaps for a server named 'ops'.
Related MCP Connectors
An MCP server that gives your AI access to the source code and docs of all public github repos
MCP server for siGit (sigit.si): browse repos, search code, manage PRs/issues, web search.
Repository knowledge graph MCP server for codebase understanding and debugging.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceRead-only GitHub MCP server that lets assistants search and read repositories, issues, pull requests, commits, and file contents, scoped to the user's personal access token.MIT
- AlicenseBqualityCmaintenanceMCP server that exposes GitHub operations as tools for AI agents, enabling code search, issue management, and PR review.12MIT
- AlicenseBqualityDmaintenanceMCP (Model Context Protocol) server for GitHub API integration. This server provides comprehensive tools for interacting with GitHub repositories, issues, pull requests, branches, and code search through a unified interface.157 npmMIT
- FlicenseAqualityDmaintenanceMCP server that wraps GitHub REST API to allow AI agents to search repositories, get repository details, list issues, and read READMEs.4-